This chapter explains the basic information about PhoneGap and how to get started with using PhoneGap. PhoneGap 3 is a big release in PhoneGap's history so far. In the older version, we had to download PhoneGap manually every time there was a new release. The pain is now over. With PhoneGap command-line interface (CLI), which was released along with PhoneGap 3, we are able to install PhoneGap directly from the command line.
PhoneGap 3 has improved the workflow for building cross-platform hybrid mobile applications. Thanks to NodeJS, creating a new project, adding a device platform, building an application, and running the application can now be performed from the command line. We don't need to open our project using each IDE, which can save us a lot of time.
Being a hybrid application means PhoneGap can give access to native functionality using web technology. We can add plugins to let our application get native capabilities. Adding plugins is easy with PhoneGap 3. Unlike older versions of PhoneGap, where we added plugins manually to each project, we can now use the CLI to add plugins to our project.
Installing PhoneGap is as easy as installing the node package manager (NPM) package. PhoneGap CLI uses NodeJS to power its command-line tool. NodeJS is a cross-platform runtime environment that uses the Google V8 JavaScript engine to execute code. NodeJS applications, including PhoneGap CLI, are written in JavaScript.
Before installing PhoneGap, you will need to ensure that you have all the required elements, as follows:
A PC or Mac running Windows, OS X, or Linux. Note that you can build and run an iOS application on OS X only.
A text editor, preferably with syntax highlighting, such as Notepad++ or Sublime Text.
As mentioned earlier, PhoneGap CLI is an NPM package, so we can easily install it using NPM. To install PhoneGap CLI, follow these steps:
First, we need to download and install NodeJS from http://nodejs.org/ for our operating system. The installation process may be different for different operating systems. To check whether it's installed or not, you can open the terminal or Command Prompt (for Windows). Run
node -vornpm -v. If you see the version number, as shown in the following screenshot, it means that you have NodeJS installed on your machine:
Checking the NodeJS and npm version
Then download and install Git client from http://git-scm.com/ if you don't have one already. PhoneGap CLI uses Git behind the scenes to download some assets during project creation.
Install the
phonegapmodule usingnpm. Thephonegapmodule will automatically be downloaded and installed by running the following commands:On Linux and OS X:
sudo npm install -g phonegapOn Windows:
npm install -g phonegap
Run the
phonegapcommand on the terminal. You will see a help message, as follows:
Running the phonegap command to get a help message
PhoneGap CLI is an NPM module, which is why we have to install NodeJS first. The NPM registry is located at https://www.npmjs.org/, and the PhoneGap CLI package is located at https://www.npmjs.org/package/phonegap.
The npm install command is a command used to install a new NPM module, and phonegap is the name of the module. The npm will search for a module named phonegap in the registry at https://www.npmjs.org/. Then, it will download the phonegap package along with its dependencies. We don't have to worry about which dependencies are used by phonegap; npm will do that for us. After the package has been downloaded successfully, npm will make the phonegap command available from the command line.
You might have noticed that we used a -g flag. This flag is used to install the module globally on our machine. It's necessary to make the phonegap module available globally so that we can run the phonegap command from anywhere, rather than only from a specific directory.
It's valuable to know how NodeJS and NPM work because PhoneGap CLI is an NPM package. A public NPM package must be registered at https://www.npmjs.org/. Each NPM package is versioned using Git and must contain a package.json file in the repository. The PhoneGap CLI repository is located at https://github.com/phonegap/phonegap-cli.
The following JSON code is the package.json file from https://github.com/phonegap/phonegap-cli/blob/master/package.json:
{
"name": "phonegap", // npm module name
"description": "PhoneGap command-line interface and node.js library.", // module description
"version": "3.5.0-0.21.18", // version number
"homepage": "http://github.com/phonegap/phonegap-cli", // module homepage
// repository type and url.
"repository": {
"type": "git",
"url": "git://github.com/phonegap/phonegap-cli.git"
},
// module keywords
"keywords": [
"cli",
"cordova",
"phonegap",
"phonegap build",
"phonegap/build"
],
// global installation is preferred
"preferGlobal": "true",
// main js file
"main": "./lib/main.js",
// binary code for the module.
"bin": {
"phonegap": "./bin/phonegap.js" // phonegap command will use ./bin/phonegap.js
},
// script is command for certain action. in this case running npm test will run jasmine-node --color spec
"scripts": {
"test": "jasmine-node --color spec"
},
"engineStrict": "true", // force to use specific node engine
"engines": {
"node": ">=0.10.0" // node engine is set to min of version 0.10.0
},
// module dependencies
"dependencies": {
"colors": "0.6.0-1",
"cordova": "3.5.0-0.2.7",
"cordova-lib": "0.21.7",
"connect-phonegap": "0.13.0",
"minimist": "0.1.0",
"phonegap-build": "0.8.4",
"pluralize": "0.0.4",
"prompt": "0.2.11",
"qrcode-terminal": "0.9.4",
"semver": "1.1.0",
"shelljs": "0.1.4"
},
// in-development module dependencies.
"devDependencies": {
"jasmine-node": "1.14.5",
"chdir": "0.0.x"
},
// module contributors
"contributors": [
{
"name": "Michael Brooks",
"email": "michael@michaelbrooks.ca",
"url": "http://michaelbrooks.ca/"
},
{
"name": "Lorin Beer",
"email": "lorin.beer@gmail.com",
"url": "http://www.ensufire.com/"
},
{
"name": "Jesse MacFadyen",
"url": "http://risingj.com"
},
{
"name": "Ryan Stewart",
"email": "ryan@adobe.com"
}
]
}Tip
Downloading the example code
You can download the example code files from your account at http://www.packtpub.com for all the Packt Publishing books you have purchased. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
NPM will download and install every dependency referenced by package.json. You will notice the cordova module among the dependencies. NPM will download the cordova module too, so you can run cordova commands from your command line.
Note
If somehow the cordova module is not installed on your machine after installing PhoneGap CLI, you can install it manually by running npm i -g cordova from the terminal.
Apache Cordova (http://cordova.apache.org/) is the software underlying PhoneGap. Previously, PhoneGap and Cordova were one software project. But after Adobe acquired Nitobi, the original developer of PhoneGap, PhoneGap code was contributed to the Apache Software Foundation as Apache Cordova.
Creating a new PhoneGap project is easy thanks to PhoneGap CLI. Unlike older versions of PhoneGap, where we needed to download the project template manually, we can create new projects directly from the command line. With just a single command, we can create a new project and start writing our application.
To create a new PhoneGap project, open your terminal or cmd. Then go to the directory where you want to maintain your source code. Run the following command:
phonegap create hello com.myapp.hello HelloWorld
It may take some time to complete the process, so be patient and let PhoneGap CLI do its magic. You will see some message during the project creation process:
Creating a new project progress
Congratulations! You have created your first PhoneGap project. Now, let's browse the project directory. You will see the directories as shown in the following screenshot:
The PhoneGap project structure
Most of the directories are empty; we will discuss the use of each directory later in the next recipe. The www/ directory is where you write code for your application. PhoneGap generated the initial starter app to work with.
The phonegap create command is a command used to create a new project. The first argument, hello, specifies a directory for your project. Note that this directory must not exist initially; phonegap will create it for you.
The second argument, com.myapp.hello, is your application ID. The application ID is used as a unique identifier for an application. Two identical applications with different application IDs will be considered two different applications. The application ID is in reverse domain style. You can create something like com.yourdomain.applicationname.
The third argument, HelloWorld, is your application name. The application name will be used as the application's display title. This argument is optional. If you are not setting the application name, it will use the name from the first argument. If you want to change the name, you can open config.xml and edit the name element.
While we are running the phonegap create command, there are several things happening in the background:
The
phonegapcreates a new PhoneGap project with the given name and ID in the newly created directory. In our case, a PhoneGap project with the name asHelloWorldand ID ascom.myapp.hellowill be created under thehellodirectory.The
phonegapdownloads the starter application and places it inwww/so that we can run the project directly after creating it.
After creating a new project, there are several things that need to be done before we are able to run the project. The workflow of PhoneGap consists of the following mandatory steps:
Creating new project.
Adding device platform.
Building the project.
Running the project.
The PhoneGap command consists of two environments. The first is the local command environment. The local commands execute the command on your local machine. In this case, you must have the target device SDKs configured on your machine. For example, if you want to develop an Android application, you must acquire and configure the Android SDK on your machine.
The second environment is remote. Command-line commands execute the build process remotely using the cloud-based PhoneGap Build service. In this case, you don't need to configure any SDK on your local machine.
We created our first PhoneGap project in the previous recipe. The next thing to do is explore the phonegap commands. Follow these steps to learn about the phonegap commands that will be used to get your application running:
Change the directory to your project directory. After creating a new project, simply run
cd helloto go to your project's directory. All furtherphonegapcommands need to be run in the project's directory.Before we can build and run our project, we have to add target platforms. The command used to add the platform is as follows:
cordova platform add <target name>The
<target name>argument is your target platform. The ability to build and run a project on your machine depends on the SDK availability for your machine. On Mac, you can run the following commands to add a specific platform:cordova platform add ios cordova platform add android cordova platform add amazon-fireos cordova platform add blackberry10 cordova platform add firefoxos
On Windows, you can add these platforms:
cordova platform add wp7 cordova platform add wp8 cordova platform add wp7 cordova platform add windows8 cordova platform add amazon-fireos cordova platform add blackberry10 cordova platform add firefoxos
You may have noticed that we are using
cordovainstead ofphonegapto add target platforms. I mentioned thatcordovais one of thephonegapdependencies, so allcordovacommands are available for thephonegapproject.Let's add the Android platform for our project by running the
cordovaplatform. Addandroid. Now browse through your project using the file explorer. You will see theandroiddirectory inside theplatforms/directory. Theandroiddirectory is an Android project. You can open it on IDEs such as Eclipse or IntelliJ. The same thing happens when we add the iOS platform. We will get theiosdirectory insideplatformsalong with the Xcode project files:
The native project inside the platforms/ directory
The next step is to build the project. Building the project means compiling your application into byte code for the target device. Run the following command to build your project:
phonegap build <platform>A PhoneGap application can run on the local development server. We can save time by testing our application on the local development server instead of running on an emulator or a real device. To run an application on the local web server, run the following command:
phonegap serveThe
servecommand has some options:--port, -p <n> Port for web server. Default port is 3000 --autoreload Enable live-reload when file changes occur. Default is true --no-autoreload Disable live-reload on file changes. --localtunnel Enabling local tunnel, will expose the local server to the your network. Default value is false
For example, to serve an application on port
1337without auto-reload, you can run the following command:phonegap serve -p 1337 —no-autoreloadInstall the application platform by running this line:
phonegap install <platform>The
installcommand has some options:—device Force installation to device —emulator Force installation to emulator
By default,
phonegapwill check whether you have a connected device or not. If a connected device is found, your application will be installed on that device. If no device is connected or found,phonegapwill install it on the emulator. You don't need to open your emulator;phonegapwill run it for you:
A PhoneGap starter application installed on an iOS simulator
To run your application, you can use the following command:
phonegap run <platform>The
runcommand has some options:—device Force application to run on device —emulator Force application to run on emulator
Just as with the
installcommand,phonegap runwill check whether you have a connected device or not, by default. If a connected device is found, your application will be run on that device. Otherwise,phonegapwill run it on an emulator:
A PhoneGap starter application running on an iOS simulator
Congratulations!!! You have created your first PhoneGap application and successfully launched it.
The PhoneGap CLI also ships a tool for integrating our application with PhoneGap Build. PhoneGap Build allows you to build your hybrid application without setting up any SDK on your local machine. Using PhoneGap Build, you can create an iOS application from Windows and create a Windows Mobile application from OS X.
To be able to use PhoneGap Build and the
phonegap remote command, you have to sign up at http://build.phonegap.com. Make sure that you don't use the GitHub single sign-on. The phonegap remote doesn't support GitHub accounts. To use the phonegap remote commands, simply follow these instructions:
Log in to your PhoneGap Build account. Simply open your command line and run this command:
phonegap remote loginYou will be prompted to fill in your e-mail address and password. If you see the following message, it means that you have successfully logged in:
[phonegap] logged in as <your email address>You don't need to add any platform to your project. To build your application, you have to run this command in your project directory:
phonegap remote build <platform>The preceding command is similar to the
phonegap build <platform>command. Instead of using an SDK on your local machine, the project build takes place on the PhoneGap Build server.You can run your application with the following command:
phonegap remote run <platform>You will notice something different from our previous
phonegap run <platform>command. Thephonegapwill not run your application directly, whether on your device or on an emulator. It will generate a QR code for you. You can scan the QR code with your phone, and it will download and install your application in your device.Note
Almost all
phonegapcommands can be replaced withcordovacommands; for example,phonegap build androidcan be replaced withcordova build android. But thephonegap remotecommand is available onphonegaponly. So you can't do something likecordova remote build android.If you are confused between Cordova and PhoneGap, read about the history of Cordova and PhoneGap at http://phonegap.com/2012/03/19/phonegap-cordova-and-what's-in-a-name/.
When building a PhoneGap application, the first thing to do is create a new PhoneGap project. PhoneGap will generate the project files automatically and give a starter application as a sample. Then we add platforms that we want to work with. For a remote-based build, we don't need to specify which platforms we want to work with. PhoneGap Build will prepare our application to work with iOS, Android, and Windows Mobile.
The main difference between local-based builds and remote-based builds is where the application building process is done. For local-based builds, PhoneGap will use the platform SDK that is installed on your machine to build the application. If the SDK is not found, PhoneGap will force you to use a remote-based build.
In the case of a remote-based build, your code will be uploaded to the PhoneGap Build server. Then the PhoneGap Build server will build your application using its machine. We do not get a device-specific project, such as an Android Eclipse project or iOS Xcode project, when using remote-based builds. What we get is a distribution-ready binary. We will get *.ipa for an iOS application and *.apk for an Android application.
A plugin is a piece of add-on code that provides an interface for native components. A plugin contains native code and a JavaScript interface. Using plugins, we can access native features using JavaScript code. We can get access to a camera, a file browser, geolocation, and so on by calling the PhoneGap JavaScript API.
The PhoneGap CLI allows us to manage plugins easily from the command line. Adding new plugins and removing existing plugins is easy now. We don't have to download and configure a plugin for each platform that we are targeting. Prior to PhoneGap 3, plugin management was a pain.
When creating a new PhoneGap project, PhoneGap doesn't include any plugins in the project. It makes our initial application clean. First, we may want to build an application without native capabilities, just like developing a web application. Then we can add plugins to extend the application.
To add a plugin to an existing project, run the following command in your project directory:
phonegap plugin add <source>
The <source> argument can be the path to the plugin directory on a local machine, the git repository, or the plugin namespace. The following commands can be used to add a plugin from the various sources mentioned before:
phonegap plugin add /local/path/to/plugin/ phonegap plugin add http://example.com/path/to/plugin.git phonegap plugin add org.apache.cordova.device
Once a plugin has been successfully added to a project, the plugin APIs can be executed using JavaScript. Each plugin has its own way of accessing native APIs, so read the documentation for each plugin.
After installing plugins, you can list all the installed plugins by running the following command:
phonegap plugin list
You will see a list of plugins installed, like this:
To remove the installed plugins, simply run the following command from your project directory:
phonegap plugin remove <id>
The <id> argument is the plugin id inside the plugin's plugin.xml file. The <id> argument is also the name of the plugin directory inside the plugins/ folder in your project. For example, if we want to remove the org.apache.cordova.device plugin, we can run this command:
phonegap plugin remove org.apache.cordova.device
When the phonegap plugin add command is executed, phonegap will copy the plugin files from the source to the project under the plugins/ directory. Each plugin will have its own directory, with the plugin ID as the directory name. Inside each plugin folder, you will find the doc/, src/, tests/, and www/ directories, along with other files.
The doc/ folder contains the plugin documentation. The src/ folder contains native code for each platform. You will see Java code for Android, Objective-C code for iOS, and so on. The tests/ folder contains JavaScript unit tests for the JavaScript interface. The last folder is www/. It contains markup, styling, media, and JavaScript code that is used for presentation and to interface with native code. The main code of the PhoneGap application will be placed in the www folder.
After the plugin is copied to the plugins directory, phonegap will update or create a .json file inside plugins/. Each platform will have its own .json file. Android will have android.json, while iOS will have ios.json. These .json files hold the plugin configuration for each platform. The following is an example of the use of plugin configurations:
Adding a new permission: Some plugins may need to add permissions to be able to work properly. Here is an example of modifying
AndroidManifest.xmlfor the Android project. A newACCESS_NETWORK_STATEpermission is added so that we can have access to the network state:"AndroidManifest.xml": { "parents": { "/*": [ { "xml": "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" />", "count": 1 } ] } }Modifying platform project files: Some plugins may need to add some configurations to each platform project. The following is an example of a configuration for modifying
res/xml/config.xmlin the Android project:"res/xml/config.xml": { "parents": { "/*": [ { "xml": "<feature name=\"NetworkStatus\"><param name=\"android-package\" value=\"org.apache.cordova.networkinformation .NetworkManager\" /></feature>", "count": 1 }, { "xml": "<feature name=\"Battery\"> <param name=\"android-package\" value=\"org.apache.cordova.batterystatus .BatteryListener\" /></feature>", "count": 1 } ] } }Declaring which plugins are used and plugin dependency: The configuration also holds information about which installed plugins are used for each platform:
"installed_plugins": { "org.apache.cordova.network-information": { "PACKAGE_NAME": "com.myapp.hello" }, "org.apache.cordova.battery-status": { "PACKAGE_NAME": "com.myapp.hello" } }, "dependent_plugins": {}
Chapter 2, Movement and Location – Using the Accelerometer and Geolocation Sensors
Chapter 3, Filesystems, Storage, and Local Databases
Chapter 4, Working with Audio, Images, and Video
Chapter 5, Working with Your Contacts List
Chapter 6, Hooking into Native Events
Chapter 11, Extending PhoneGap with Plugins
