Introduction
Apache Cordova is a build system for creating native apps with bundled HTML and JavaScript content. Apps built with Cordova are native apps that can be published on the app stores. Furthermore, you can add custom native plugins to extend the functionality of your app.
To learn how to install Cordova and mobile SDKs on your system, please go to the Build Overview.
Below we will show how to set up and build a Cordova project. Cordova is based on working with the command line in a terminal window (Cordova CLI = Command Line Interface). Do not fear! The commands for building apps are quite simple.
You can also consult the Cordova documentation to learn more about how to set up and build projects: cordova.apache.org/docs/en/3.5.0/guide_cli_index.md.html
Creating a Cordova Project (iOS and Android)
Here is how to create a new Cordova project (procedure is the same for all platforms):
Open a command-line window
Go to a folder where you want the project subfolder to be created.
Use the cordova create command to create a project. This command has the following form:
cordova create project-folder app-identifier app-name
Here is an example that will create a folder called "DemoProject" with project template files:cordova create DemoProject com.evothings.demoapp DemoApp
Note that creating the project may take a while.To issue further Cordova commands, move into the project folder, e.g. by typing:
cd DemoProject
Building for iOS
Here is how you build your new Cordova project for iOS:
Make sure you are in the project folder in a terminal window
Add the iOS platform to the project. Note that this only needs to be done once for each project:
cordova platform add ios
Build the project:
cordova build ios
The output is an Xcode project, located in subfolder platforms/ios. Open a Finder window and navigate to the folder, there you will find the file DemoApp.xcodeproj (assuming you named your app "DemoApp"). Open this file to launch the project in Xcode. From Xcode you can run the app in the iOS simulator, or deploy the app to a devices (deploying to device requires membership in Apple's iOS Developer Program).
Building for Android
Here is how you build your new Cordova project for Android:
Make sure you are in the project folder in a terminal window
Add the Android platform to the project. Note that this only needs to be done once for each project:
cordova platform add android
Build the project:
cordova build android
The output is a debug-signed apk-file, located in subfolder platforms/android/ant-build
Deploy the apk-file to a device using the adb install command (adb = Android Debug Bridge, a command-line tool for Android).
Deploying the app to a device is a bit different depending on which operating system you are using, because of the different path separators used.
Windows:
adb install -r platforms\android\ant-build\DemoApp-debug.apk
OS X:
adb install -r platforms/android/ant-build/DemoApp-debug.apk
Linux:
adb install -r platforms/android/ant-build/DemoApp-debug.apk
Above examples assume you named your app "DemoApp".
The switch "-r" means "reinstall" and will overwrite the app if it is already installed (this is convenient, because then you don't have to uninstall the app before installing it again).
Adding Plugins
Cordova plugins add native functionality to JavaScript. Here is how to add plugins to your project:
Open a terminal window and go to the Cordova project folder.
Use the cordova plugin add command to add plugins. Here are examples of plugins to add:
cordova plugin add org.apache.cordova.device
cordova plugin add org.apache.cordova.console
cordova plugin add org.apache.cordova.vibration
Read more about plugins in the Cordova documentation: cordova.apache.org/docs/en/3.5.0/guide_cli_index.md.html
Documentation for standard Cordova plugins: cordova.apache.org/docs/en/3.5.0/cordova_plugins_pluginapis.md.html
Cordova Directory Structure
This is the directory layout of a generated Cordova project. Put your HTML/CSS/JS in folder www. Edit config.xml to include the relevant settings for your project. Build output is found in the platforms folder.
config.xml (specify main HTML-file or URL here) hooks (build hooks - for advanced use) merges (platform overrides - for advanced use) platforms ios (Xcode project is found here) android ant-build (generated apk-file is found here) plugins (plugins are added here) www index.html (main HTML-file specified in config.xml)
The main HTML-file display when your app launches is specified in config.xml. Usually this file is named index.html, but you can name it anything as long as the name matches the setting in config.xml. You can also specify a connect URL to Evothings Workbench, read on below for further details.
Workflow Speedup
You can use Cordova as is, without using Evothings Studio. But the workflow will be much faster if you use Evothings. Below we compare the two workflows.
Cordova Workflow
Typical workflow when using Cordova WITHOUT Evothings Studio is as follows:
Edit your code (HTML/JS) and save
Build the app (cordova build ios/android)
Deploy the app to a device (adb install -r path-to-apk-file)
Launch the app on the device
Repeat above steps for each code change
Evothings/Cordova Workflow
Workflow when using Cordova WITH Evothings Studio:
Edit your code (HTML/JS) and save
The app is instantly reloaded on the device(s)
In the next section, we describe how to setup a Cordova project for use with Evothings Studio.
Setup Your Cordova Project for Evothings
Evothings Workbench monitors the files in the current project and reloads the project on connected clients when a file is updated. This works with any web browser or web view widget. Automatic reload-on-save works with any Cordova project.
Note that the Evothings Client app itself is built with Cordova. It is a plain Cordova app with some custom plugins added, e.g. for socket communication and Bluetooth Low Energy (BLE).
To Evothings-enable your Cordova project, do as follows:
Launch Evothings Workbench.
Copy the connect address displayed in the bottom panel of the Workbench window.
Open the file config.xml (located in your Cordova project folder) in a text editor.
On this line, replace the start page of the Cordova project ("index.html") with the connect address of the Workbench:
<content src="index.html" />
For example, if the address is "192.168.43.131:4042", you would enter this URL:<content src="http://192.168.43.131:4042" />
Save the file.Build the project and launch the app on a device. Note that the device must be on the same network as your desktop machine running Evothings Workbench. When you launch the app, it should connect to the Workbench and display the Connect screen.
Find the index.html file of you project in the www folder using a file explorer (Finder on iOS X, Explorer on Windows).
Drag the file index.html into the Evothings Workbench window. This adds your project to the project list.
Click the Run button of your project.
Now you can just edit your HTML/CSS/JS files in any text editor. When you save a file, the app will be reloaded on the device!
Note that you can run your app on multiple devices/platforms, for instance an Android tablet and an iPad. When you update your code, the app will be reloaded on all connected devices!
Supported Platforms
Supported mobile platforms for Evothings are iOS and Android.
Cordova comes with a set of plugins that are supported for a wide range of platforms. Evothings apps can use custom plugins available for iOS and Android. As long as you do not require socket communication or BLE, you should be able to use Evothings Studio to build apps for any platform supported by Cordova.
The same goes for the Evothings Client app. It is available on iOS and Android, but should be possible to build from source for any platform supported by Cordova. (But you would miss the plugins not available for the target platform.)
Copyright © 2013-2014 Evothings AB