Using Cordova (PhoneGap) API - Quick Start

1. Introduction

The MobiOne App Center Builder (app build services) creates HTML5 apps from your MobiOne project using the Cordova (formerly PhoneGap) HTML5 app runtime and API. Thus, the JavaScript cordova.js API is available to your iOS and Android applications. This guide provides a quick introduction for using the Cordova JavaScript API from within your MobiOne application.

Visit the Apache Cordova project for project information and API documentation.

1.1 Prerequisites

For this quick start, you need:

  • One of the following devices on which to test the MobiOne app:

    • Android device or emulator with Android OS version 2.2 or higher
    • iOS device (iPhone, iPad, iPod Touch) with iOS version 4.3 or higher. Note: iOS app development requires you to provide digital signing data and a provision profile.
  • MobiOne Studio installed
  • Basic JavaScript coding know-how

 

2. What Version of Cordova is Used?

In the App Center settings, you can choose the Cordova version used by the App Center Builder. From the Design Center settings, choose the App Center category followed by the Cordova runtime environment you want to use.

App Center Builder: Cordova Runtime Settings

Following are the current Cordova runtimes from which to choose:

  • Cordova 2.9 - InAppBrowser replaces ChildBrowser, lots of bug fixes
  • Cordova 2.2 - ChildBrowser (deprecated)

 

3. Cordova.js API Library

Where do I install the Cordova.js Library? You don't! We frequently update the version of Cordova used by App Center Builder to provide the most current Cordova features and fixes. As a convenience, App Center Builder automatically injects the compatible version of the cordova.js library into your project code at build time. Thus, you do not need to explicitly include the cordova.js file in your project to use the Cordova JavaScript API.

But, suppose you want to use developer tools or an IDE that provides smart JavaScript editing with API code assist and syntax validation. Such editors typically load and analyze JavaScript files imported by the project's main HTML file. Because we recommend omitting the cordova.js file from your HTML file(s), you need to download the version of cordova.js matching the Cordova version used by App Center. Then, configure your editor to reference the library. For example, from within MyEclipse, create a JavaScript Library that contains cordova.js, and add it to your project.

You can explicitly override the App Center's cordova.js injection process by including your version of cordova.js as an Additional JavaScript Library in Design Center. Include the file in the properties of your project's startup screen file (.mobi). The library file must be named cordova.js to be recognized by App Center Builder.

 

4. Example - Vibrate Device Demo

Let's walk through a quick app example that uses the Cordova notification.vibrate() API to vibrate your device. Download the source code for this demo to view the project - vibrate-example.zip.

4.1 Keep the Online Cordova API Docs Handy

Before beginning, you should familiarize yourself with the API you plan to use. All versions of the Cordova API documentation can be found online at http://cordova.apache.org/docs/en/2.2.0/. Select your language and version of the Cordova API.

Cordova API reference

Below is the documentation for the notification module's vibrate API used in this example.

Notification vibrate documentation

4.2 Wait for the Cordova deviceready Event

Before you can use the Cordova JavaScript API, you must wait for the Cordova Runtime Environment to be loaded and initialized by the app. The Cordova runtime signals when it has completed initialization by emitting the "deviceready" event. Register a deviceready event listener in the documentReady() function generated by the MobiOne Design Center in the <projectname>_custom.js file.

function documentReady() {
   document.addEventListener("deviceready", handleDeviceReady, false);
}

function handleDeviceReady(event) {
   //cordova api is ready for use
}

4.3 Design & Code

Use the MobiOne Visual Designer to create this simple one-screen app. The screen contains a button that, when tapped, vibrates the device for one second. If the device does not have a vibrate feature, an alert message pops up when the button is tapped.

4.3.1 UI Design

The Vibrate button calls the vibrate() JavaScript function you will create in the next section. The file is saved as vibrate.mobi.

    Button with Run JavaScript onClick action property

    4.3.2 Generate Application Code

    Before you can implement the vibrate() function, you need to generate the project HTML code.

  1. In the Visual Designer, click the Set Target Design button .
  2. Select Project>Generate Application Files from the menu to generate the project's HTML5 code.
  3. In the File Explorer view, navigate to the generated vibrate-www folder, which contains the generated app files. To find the folder easily, be sure the Link with Editor toggle is enabled.
  4. Navigating to the generated source files

4.3.3 JavaScript Coding

Next, implement the Vibrate button's vibrate() function and state tracking logic to ensure the deviceready event has been received before using the Cordova vibrate() API. Open the vibrate_custom.js file by double-clicking the file in the File Explorer view.

    JavaScript file open for editing

Following is the code to implement registering a deviceready callback handler, tracking the state, and vibrating the device.

// vibrate_custom.js

isDeviceReady = false; // flag indicates if cordova is initialized

/**
* Called when document is loaded.
*/
phoneui.documentReadyHandler = function() {
  //list for cordova runtime initialized for use
  document.addEventListener('deviceready', handleDeviceReady, false);
}

function handleDeviceReady(event) {
  //cordova is ready for use
  isDeviceReady = true;
}

//called by Vibrate button's OnClick RunJS action
function vibrate() {
  if (phoneui.cordovaAvailable()){
    if (isDeviceReady) {
      navigator.notification.vibrate(1000); // 1000ms = 1sec
    } else {
      phoneui.alert("Cordova not initialized, try again");
    }
  } else {
    phoneui.alert("Cordova vibrate is not available");
  }
}

 

5. Testing your App

With vibrate.mobi set as the target design, click the Run in Mobile Simulator icon on the toolbar to open the design in the Mobile Web Simulator for testing. Another testing option is to build your project into an app and run it on your target device. The app building process is simple and quick.

Note: If building an Android app that uses a Cordova API, you must select the associated service in the Build Android Application wizard. In the vibrate notification example, you must select the Notifications service.

Selecting required services