PhoneGap is a free and open source framework that allows you to create mobile apps using standardized web APIs for most mobile platforms. (PhoneGap is an open source distribution of Apache Cordova - think of the relationship between FireFox and WebKit).
This wiki will describe how to setup the development environment and build cross-platform applications with PhoneGap and Apache Cordova.
Note: This documentation is based on PhoneGap 3.5 and Cordova 3.5
Setting Up The Development Environment
You can set up and control all your development environment using
npm. Nifty eh?
Before being able to setup your environment to develop against the different platforms supported by PhoneGap, you will need to install the SDK. See PhoneGap’s Platform guides for additional information.
Installing the PhoneGap/Cordova CLI
You can then install phonegap and cordova using
> npm install -g phonegap > npm install -g cordova
This will install both phonegap and cordova command line interfaces. They are slightly different and you will be using them to boostrap your app, add platforms to your project, build and run the different emulators. When both CLI can be used I will provide examples of both, and when only one of them provides the mentioned feature or the commands behave in different ways I will make it clear.
Creating a Sample PhoneGap App
To create a sample application you can use the following command:
cordova create <folder> <project-identifier> <project-name> > cordova create hello com.example.hello HelloWorld
> phonegap create hello com.example.hello HelloWorld
Either of these commands will create a sample PhoneGap application and will place it in the indicated folder.
The Structure of a PhoneGap App
A PhoneGap App will have the following folders:
- platforms: This is where your app will be built in a suitable format for each platform that you decide to target. Every time that you run a build or deploy command, phonegap will generate a platform-specific project based on the contents of the
merges/android/styles.csswill deploy that stylesheet only to the android platform.
- hooks: Here you hook into phonegap’s building/deployment process by placing scripts in different folders to extend/customize these processes.
A Cordova App will not have a
.cordova folder and instead will place a
config.xml (as opposed to
config.json) in the root folder of the app.
Adding Platforms to Your App
You can add support for new platforms to your PhoneGap app by using the
cordova platform add as long as you have the proper SDKs installed in your machine.
# add platform cordova platform add <platform> > cordova platform add ios > cordova platform add android > cordova platform add wp8 > cordova platform add windows8 # list current platforms > cordova platform ls
Note: as far as I know only cordova provides a command to add a platform to your app without building and deploying it. The most similar command in phonegap is the install command.
As hinted in above, running this command will create a new folder for each specific platform under the
platforms folder that will replicate your
www. Because of this, you should only edit the files located under
www and not those at
platforms (which are constantly generated and would render any changes useless as they would be overwritten). Moreover, the
www is the folder that you want to keep in source control (together with the
Building the App
You can build your PhoneGap app for all specified platforms via:
> cordova build
Or for a specific platform like so:
cordova build <platform> > cordova build ios > cordova build wp8
This will essentially deploy whatever you have in
www folder to the corresponding
platforms directory. The
cordova build <platform> is shorthand for
cordova prepare <platform> (copy files to platform) and
cordoba compile <platform> (build app in platform).
Deploying the App to an Emulator or Device
You can deploy your app to an emulator by using the
emulate command. This will rebuild the app and deploy it based on your SDK and
platform project configuration:
cordova emulate <platform> > cordova emulate ios > cordova emulate android > cordova emulate wp8
You can also depoy your app to a real device by using the
cordova run <platform> > cordova run ios > cordova run android > cordova run wp8
Plugins provide you a way to access device APIs in PhoneGap/Cordova. A plugin is a wrapper that exposes a interface to native phone components.
The core Cordova APIs are:
- Battery status
- Device motion (accelerometer)
- Device orientation (compass)
- File system and transfer
- In-app browser
- Media playback and capture
- Network information
Developing Your Own Plugins
To find more informationa about how to develop your own plugins go to the Cordova Official Docs.
Customizing Apps by Platform
Developing a PhoneGap App
Written by Jaime González García , Dad, Husband, Front-end software engineer, UX designer, amateur pixel artist, tinkerer and master of the arcane arts. You should follow him on Twitter where he shares useful stuff! (and is funny too).Follow @vintharas