PhoneGap 4 Mobile Application Development Cookbook

Chapter 1. Welcome to PhoneGap 3

In this chapter, we will cover the following recipes:

Installing PhoneGap 3
Creating a new project
Using the command line
Installing API plugins

Installing PhoneGap 3

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.

Getting ready

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.

How to do it…

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 -v or npm -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 phonegap module using npm. The phonegap module will automatically be downloaded and installed by running the following commands:
- On Linux and OS X:
```
sudo npm install -g phonegap
```
- On Windows:
```
npm install -g phonegap
```
Run the phonegap command on the terminal. You will see a help message, as follows:
Running the phonegap command to get a help message

How it works…

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.

Note

NPM is like gem to Ruby and Composer to PHP if you have worked with Ruby or PHP before.

There's more…

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 project

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.

How to do it…

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.

How it works…

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 phonegap creates a new PhoneGap project with the given name and ID in the newly created directory. In our case, a PhoneGap project with the name as HelloWorld and ID as com.myapp.hello will be created under the hello directory.
The phonegap downloads the starter application and places it in www/ so that we can run the project directly after creating it.
Tip
You can use the -d option with any phonegap command to allow a verbose output. The -d option will give clear information about what is going on and the current status of the command.

Using the command line

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.

How to do it…

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.

The local commands

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 hello to go to your project's directory. All further phonegap commands 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 cordova instead of phonegap to add target platforms. I mentioned that cordova is one of the phonegap dependencies, so all cordova commands are available for the phonegap project.
Let's add the Android platform for our project by running the cordova platform. Add android. Now browse through your project using the file explorer. You will see the android directory inside the platforms/ directory. The android directory 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 the ios directory inside platforms along with the Xcode project files:
The native project inside the platforms/ directory
Tip
When PhoneGap and Cordova release a new version, we should update our platform-specific project by running phonegap platform update <platform>.
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 serve
```

The serve command 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 1337 without auto-reload, you can run the following command:
```
phonegap serve -p 1337 —no-autoreload
```
Install the application platform by running this line:
```
phonegap install <platform>
```

The install command has some options:

—device            Force installation to device
—emulator        Force installation to emulator

By default, phonegap will 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, phonegap will install it on the emulator. You don't need to open your emulator; phonegap will run it for you:
A PhoneGap starter application installed on an iOS simulator
Note
To be able to run an application directly on your Android device, you have to enable USB debugging on that device.
To run your application, you can use the following command:
```
   phonegap run <platform>
```

The run command has some options:

—device            Force application to run on device
—emulator        Force application to run on emulator

Just as with the install command, phonegap run will 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, phonegap will 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 remote commands

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 login
```
You 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. The phonegap will 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 phonegap commands can be replaced with cordova commands; for example, phonegap build android can be replaced with cordova build android. But the phonegap remote command is available on phonegap only. So you can't do something like cordova 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/.

How it works…

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.

Installing API plugins

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.

How to do it…

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.

Adding plugins

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.

Tip

You can search for an existing plugin using the cordova plugin search <keyword> command.

Listing plugins

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:

Removing plugins

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

How it works…

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.xml for the Android project. A new ACCESS_NETWORK_STATE permission 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.xml in 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": {}