Touch Sencha Docs

Cordova and PhoneGap Apps

Apache Cordova provides APIs and packaging tools for creating an app for an Android, iOS, BlackBerry, or Windows Phone device. Touch 2.3 introduces tools and an API for working with Cordova and PhoneGap.

PhoneGap is built on top of Cordova and both have access to the Cordova API. PhoneGap and Cordova differ by how their packaging tools are implemented. PhoneGap provides a remote building interface at Adobe PhoneGap Build that lets you package and emulate an app for a single platform in the cloud. Cordova packaging tools let you build simultaneously for multiple platforms on your computer. In addition, Cordova is constantly updated by the open source community, whereas PhoneGap updates are coordinated by Adobe.

While Cordova and PhoneGap make it easy to package an app, you still need a certificate and AppID for each platform for the market in which you want to distribute your app, such as for Google Play or the Apple App Store.

Sencha Cmd version 4.0 and later provides access to Cordova and PhoneGap. You can easily enable or disable access, package an app, and run an emulator or simulator. You can use the Sencha Cmd Cordova and PhoneGap commands to package and emulate a Touch app.

See the Apache Cordova Platform Guides for information.

Important Notes

  1. Don't use the packager.json file with Cordova or PhoneGap. Instead, put your configuration parameters in the config.xml file. See also: PhoneGap example config.xml file

  2. For Cordova and PhoneGap, Sencha Cmd can only create DEBUG versions of applications, not a Release (for an app store) version. To create release versions, you have to use a packager such as Eclipse or IntelliJ for Android, or Xcode for iOS.

  3. While PhoneGap builds BlackBerry version 10 locally, the BlackBerry version at the Adobe PhoneGap Build site is version 6.

  4. You must have Java JRE 1.7 on your computer for the Sencha Cmd Cordova commands to work correctly. If you cannot upgrade your computer to Java 1.7, you can replace the cordova-impl.xml files in Sencha Cmd and in your app's directory as explained in Patch Sencha Cmd 4.0.0.203 to Work with Java 1.6.

Before Creating an App

Before developing an app:

  1. Install Java JRE.

  2. Install Node.js

  3. If you plan to package and emulate with Cordova, after Node.js is installed, use this command to install Cordova:

    npm install -g cordova

    Important Whether or not you install Cordova to package and emulate your app, the Cordova API is available to your apps. The Cordova packaging and emulating package does not affect the use of the Cordova APIs in a Cordova or PhoneGap app.

  4. If you plan to package and emulate with PhoneGap, after Node.js is installed, use this command to install PhoneGap:

    npm install -g phonegap

    Notes:
    • You must register with the free Adobe PhoneGap Build site and obtain a username and password to access the PhoneGap remote building site.
    • Sencha recommends that you install both Cordova and PhoneGap--both are free (as is access to the Adobe PhoneGap Build site). Both software packages provide features that help your app development.

  5. Install Sencha Cmd version 4.0 or later.

  6. Create your app's file structure with:

    sencha -sdk /path/to/SenchaTouch generate app MyApp /path/to/MyApp

    For more information, see the Getting Started guide.

  7. If you are developing for Android, download the Android SDK Manager.

  8. If you are developing for iOS, complete iOS provisioning on the Apple iOS provisioning profiles portal (requires an Apple ID, password, and a purchased developer license). Use this site to obtain a certificate, identify devices, and get an AppID. In addition, download and install the free Xcode software. You can use the Xcode simulator to debug your iOS app before installing your app on a device. Xcode only works on a Mac with the Lion, Mountain Lion, or Mavericks OS X versions.

  9. If you are developing for BlackBerry, review the BlackBerry Native SDK and register to sign your apps with the BlackBerry Keys Order Form.

  10. Create a config.xml using the information provided by PhoneGap. This file resides at the root level of your project where your index.html file resides. If you are porting from packager.json to Cordova, the config.xml file is not similar, however, after you register your app with the Apple Developer Program, and for Android in the AndroidManifest.xml file, most of the parameters in packager.json will be provided for. In addition, the default settings in config.xml handle most app conditions, so there will be fewer items to change.

    See also:
    PhoneGap example config.xml file
    Configuration Reference

Developing a Cordova or PhoneGap App

To develop an app:

  1. Change directory to your project directory.

  2. Initialize access for Cordova or PhoneGap.

    Note: You can initialize your app for Cordova OR PhoneGap, but not both. To switch SDKs, use the appropriate "remove" command before initializing the other SDK.

    If initializing access for iOS, see iOS Note below.

    To initialize access to Cordova, use:

    sencha cordova init [AppID]

    To enable support for PhoneGap, use:

    sencha phonegap init [AppID]

    The AppID is not the same as the AppID in your project's app.json file. For iOS, you get the AppID from Apple's portal. An example AppID is com.example.TestApp - in reverse domain format to be more unique.

    The AppID in Android can be any unique string, also in reverse domain format.

    If you do not supply an AppID value, Touch assumes that your AppID is:

    foo.bar.AppName

    Where the AppName value is taken from your config.xml file.

    If you need to remove support for Cordova or PhoneGap, see the Remove Note below.

  3. If using Cordova, configure the cordova.local.properties file to indicate which platforms you're building for. This file contains a single statement and lists the build targets separated by a space - this example lists all the target platforms:

    cordova.platforms=ios android blackberry wp8
  4. If using PhoneGap, configure the phonegap.local.properties file to indicate which platforms you're building for. This file contains information you need to pass to the Adobe PhoneGap Build site to create your app - PhoneGap only lets you specify one platform at a time:

    phonegap.platform=ios
    phonegap.build.remote=true
    phonegap.build.remote.username=<Your_PhoneGap_Username>
    phonegap.build.remote.password=<Your_PhoneGap_Password>
    

    Note If you set phonegap.build.remote=false, PhoneGap builds locally on your computer.

  5. Use the Cordova API to develop your app. Touch 2.3 provides an extensive set of device APIs in the Ext.device.<API>.Cordova and Ext.device.<API>.PhoneGap namespaces. Alternatively, you can access the Cordova functions directly in your app by preceding the API with navigator, for example for the Compass API, use:

    navigator.compass.getCurrentHeading(compassSuccess, compassError, compassOptions);
  6. Create your app using Sencha Touch or Sencha Architect.

  7. Emulate your app with:

    sencha app build -run native
  8. Package a Debug app with:

    sencha app build native

iOS Note

If your app runs on iOS, supply a unique AppID that you get from the Apple developer site. Access to the Apple developer site requires that you specify your Apple Developer username and password.

Remove Note

You can remove support for Cordova or PhoneGap with:

sencha cordova remove

Or for PhoneGap with:

sencha phonegap remove

The remove command also deletes these files in your project directory:

  • If Cordova, the cordova.local.properties file.
  • If PhoneGap, the phonegap.local.properties file.
  • The config.xml file.

Sencha Cmd Ant Commands

Starting with Sencha Cmd version 4.0, the Cordova/PhoneGap implementation provides extra functionality that you can access using the Ant component in Sencha Cmd.

CommandDescription
sencha ant cordova-build Builds all platforms without building the Sencha app.
sencha ant cordova-clean Deletes all files in the general {project}/cordova/www folder.
sencha ant cordova-emulate Emulates all platforms without building the Sencha app.
sencha ant cordova-prepare Prepares all platforms without building the Sencha app.
sencha ant cordova-sencha-build Builds into the Cordova general {project}/cordova/www folder. When you specify the sencha cordova init command, Cordova creates this folder for you. Important This folder is overwritten on each build. Never put files of your own in the www folder.
sencha ant cordova-sencha-emulate Builds then emulates in all platforms.
sencha ant cordova-sencha-prepare Builds then Emulates in all platforms.
sencha ant phonegap-build Builds then Emulates in all platforms.
sencha ant phonegap-clean Deletes all the files in the {project}/phonegap/www folder.
sencha ant phonegap-run Runs the native app without building the Sencha app.
sencha ant phonegap-sencha-build Builds the Sencha app and the PhoneGap native platform.
sencha ant phonegap-sencha-run Builds the Sencha app and the PhoneGap native app then runs the native app.

More Information