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 node.js and npm. Nifty eh?

Prerequisites

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 like:

> 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

or

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

• www: This is where your PhoneGap app itself will reside with all the html, javascript and css files.
• 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 www folder.
• merges: This folder contains platform specific HTML, JavaScript and css files. For instance, placing a css file in merges/android/styles.css will deploy that stylesheet only to the android platform.
• plugins:
• 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 merges folder).

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

See the device platform guides for more information regarding configuring emulators in different platforms.

You can also depoy your app to a real device by using the run command:

cordova run <platform>
> cordova run ios
> cordova run android
> cordova run wp8

Plugins

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
• Camera
• Contacts
• Device
• Device motion (accelerometer)
• Device orientation (compass)
• Dialogs
• File system and transfer
• Geolocation
• In-app browser
• Media playback and capture
• Network information
• Splashscreen
• Vibration

A list of all plugins available, both core cordova plugins and community plugins is available at plugins.cordova.io*.

Installing Plugins

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

Help

Updating Cordova

Developing a PhoneGap App

Ionic