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.
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.
While PhoneGap builds BlackBerry version 10 locally, the BlackBerry version at the Adobe PhoneGap Build site is version 6.
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.xmlfiles in Sencha Cmd and in your app's directory as explained in Patch Sencha Cmd 188.8.131.52 to Work with Java 1.6.
Before Creating an App
Before developing an app:
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.
If you plan to package and emulate with PhoneGap, after Node.js is installed, use this command to install PhoneGap:
npm install -g phonegap
• 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.
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.
If you are developing for Android, download the Android SDK Manager.
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.
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.jsonto Cordova, the
config.xmlfile 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.jsonwill be provided for. In addition, the default settings in
config.xmlhandle most app conditions, so there will be fewer items to change.
Developing a Cordova or PhoneGap App
To develop an app:
Change directory to your project directory.
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.jsonfile. 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:
Where the AppName value is taken from your
If you need to remove support for Cordova or PhoneGap, see the Remove Note below.
If using Cordova, configure the
cordova.local.propertiesfile 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
If using PhoneGap, configure the
phonegap.local.propertiesfile 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.
Use the Cordova API to develop your app. Touch 2.3 provides an extensive set of device APIs in the
Ext.device.<API>.PhoneGapnamespaces. 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);
Create your app using Sencha Touch or Sencha Architect.
Emulate your app with:
sencha app build -run native
Package a Debug app with:
sencha app build native
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.
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
- If PhoneGap, the
- 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.
|sencha ant cordova-build||Builds all platforms without building the Sencha app.|
|sencha ant cordova-clean||Deletes all files in the general |
|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 |
|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 |
|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.|