Cordova Guide
Summary of build steps
Creating a Cordova Project
Building for iOS
Building for Android
Adding plugins
Cordova file structure
Workflow speedup
Customise Evothings Viewer
Setup a Cordova project with Evothings
Use Evothings Studio

Cordova Guide

Apache Cordova is a build system for creating native mobile 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 an app.

To learn how to install Cordova and mobile SDKs on your system, please review the Build and publish guide.

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 build apps.

Summary of build steps

When you have used Evothings Viewer to develop an app it is straightforward to create a Cordova app from your project files. In essence, just put your HTML/CSS/JS files into the Cordova "www" folder. That's it!

You can also run your Cordova app from Evothings Workbench, and take advantage of the fast reload-on-save functionality. This means there is no need to rebuild the Cordova app during development, unless you made native code changes such as adding a new plugin.

Here is a step-by-step guide for how to create a Cordova app from your Evothings project. For details regarding each step, see sections below.

Initial setup to create the project:

  • Create a new Cordova project.

  • Delete the contents of the www folder.

  • Move or copy the files from the Evothings project folder to the Cordova www folder.

  • Add plugins needed.

  • Add target platforms (ios and/or android).

For each code update:

  • Build for the target platforms

Example of one-time initial setup:

cordova create DemoProject com.evothings.demoapp DemoApp
cd DemoProject
(delete files in www-folder, using file browser or command line)
(move or copy files from your project to www, using file browser or command line)
(add plugins using cordova plugin add)
cordova platform add ios
cordova platform add android

Then build the native app (for iOS and Android):

cordova build ios
cordova build android

As mentioned, to save development time you can use Evothings Workbench when developing a Cordova app. This gives you a fast reload-on-save workflow.

Read further below for detailed descriptions of the steps outlined above.

Creating a Cordova project (iOS and Android)

Here is how to create a new Cordova project (procedure is the same for all platforms):

  1. Open a command-line window

  2. Go to a folder where you want the project subfolder to be created.

  3. 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.

  4. 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:

  1. Make sure you are in the project folder in a terminal window

  2. Add the iOS platform to the project. Note that this only needs to be done once for each project: 

    cordova platform add ios

  3. Build the project: 

    cordova build ios

  4. 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:

  1. Make sure you are in the project folder in a terminal window

  2. Add the Android platform to the project. Note that this only needs to be done once for each project: 

    cordova platform add android

  3. Build the project: 

    cordova build android

  4. The output is a debug-signed apk-file, located in subfolder platforms/android/ant-build

  5. 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:

  1. Open a terminal window and go to the Cordova project folder.

  2. 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 and the Cordova CLI.

Cordova file 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
hooks
  (build hooks - for advanced use)
merges
  (platform overrides - for advanced use)
platforms
  ios
    (Xcode project is found here)
  android
    build
      outputs
        apk
          (generated apk-file is found here)
plugins
  (plugins are added here using the command line)
www
  index.html (main HTML-file specified in config.xml)
  (other HTML/CSS/JS files used by the app)

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.

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:

  1. Edit your code (HTML/JS) and save

  2. Build the app (cordova build ios/android)

  3. Deploy the app to a device (adb install -r path-to-apk-file)

  4. Launch the app on the device

  5. Repeat above steps for each code change

Evothings workflow

Workflow when using Evothings Studio:

  1. Edit your code (HTML/JS) and save

  2. The app is instantly reloaded on the device(s)

Customise Evothings Viewer

Evothings Viewer is an app build with Cordova. You can use Evothings Viewer out-of-the-box, just install it from the app stores. This works fine as long as the plugins bundled with the Viewer fits your needs.

If you need plugins not included with the stock Viewer, you can easily build your customised version. The GitHub repository contains the full source code for Evothings Viewer, along with instructions for how to customise the Viewer with your preferred set of plugins.

Building your own version of Evothings Viewer is the easiest way to get the benefits of the fast Evothings workflow for Cordova app development.

Just edit the file package.json and add/remove plugins to suit your project.

Setup a Cordova project with Evothings

Evothings Workbench monitors the files in the current project and reloads the app in connected Viewers when a file is updated. Automatic reload-on-save works with any Cordova project running in EVothings Viewer.

Note that Evothings Viewer itself is built with Cordova, with plugins added for e.g. socket communication and Bluetooth Low Energy (BLE).

Here is how to develop your Cordova app with Evothings:

  1. Generate a Cordova project (works perfectly fine to use an existing project).

  2. Launch Evothings Workbench on your computer.

  3. Launch Evothings Viewer on your mobile phone(s). Build a custom Viewer if you need plugins not included with the stock Viewer found on the app stores.

  4. Locate index.html in the www folder of your Cordova project using a file explorer (Finder on iOS X, Explorer on Windows).

  5. Drag index.html into the Evothings Workbench window. This adds your project to the "My Apps" screen.

  6. Click the Run button of your project. Clicking Run activates your project, and tells the Workbench that this is the project to reload when changes are made. You only need to click Run once. Edit code in your usual editor. When you save a file the app will automatically reload in the Viewer running on connected mobile devices.

When you wish to build a stand-alone Cordova app, just build your Cordova project the usual way.

When running the app in the Workbench, a file called evothings.json is created in the www folder. This file contains data used by the Workbench. There should be no harm in leaving this file as it is when building a stand-alone Cordova app, but you can of course exclude it if you would prefer that.

You can run your app on multiple devices/platforms at the same time, for instance an Android tablet and an iPad. When you save your code, the app will be reloaded on all connected devices.

Use Evothings Studio for Cordova app development

Evothings Studio makes it easy to develop Cordova apps. Check out how to use your Cordova project with the fast Evothings workflow.

It is easy and fun to get started with Evothings Studio. Download now and be up and running in 5 minutes!