In this chapter, we will cover the following recipes:
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 Phone Gap 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:
As mentioned earlier, PhoneGap CLI is an NPM package, so we can easily install it using NPM. To install PhoneGap CLI, follow these steps:
sudo npm install -g phonegap
npm install -g phonegap
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.
NPM is like gem to Ruby and Composer to PHP if you have worked with Ruby or PHP before.
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.
< "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" >] >
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.
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:
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.
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:
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:
cordova platform add
cordova platform add ios cordova platform add android cordova platform add amazon-fireos cordova platform add blackberry10 cordova platform add firefoxosOn 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
When PhoneGap and Cordova release a new version, we should update our platform-specific project by running phonegap platform update
phonegap build
phonegap serve
--port, -p 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
phonegap serve -p 1337 —no-autoreload
phonegap install
—device Force installation to device —emulator Force installation to emulator
To be able to run an application directly on your Android device, you have to enable USB debugging on that device.
phonegap run
—device Force application to run on device —emulator Force application to run on emulator
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:
phonegap remote login
[phonegap] logged in as
phonegap remote build
phonegap remote run
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/.
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
The 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.
You can search for an existing plugin using the cordova plugin search command.
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
The argument is the plugin id inside the plugin's plugin.xml file. The 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:
"AndroidManifest.xml": < "parents": < "/*": [ < "xml": "", "count": 1 > ] > >
"res/xml/config.xml": < "parents": < "/*": [ < "xml": "", "count": 1 >, < "xml": " ", "count": 1 > ] > >
"installed_plugins": < "org.apache.cordova.network-information": < "PACKAGE_NAME": "com.myapp.hello" >, "org.apache.cordova.battery-status": < "PACKAGE_NAME": "com.myapp.hello" >>, "dependent_plugins": <>
2. Movement and Location – Using the Accelerometer and Geolocation Sensors Chevron down icon Chevron up icon
Movement and Location – Using the Accelerometer and Geolocation Sensors Introduction Detecting device movement using the accelerometer Adjusting the accelerometer sensor update interval Updating a display object position through accelerometer events Obtaining device geolocation sensor information Adjusting the geolocation sensor update interval Retrieving map data through geolocation coordinates Creating a visual compass to show the device direction 3. Filesystems, Storage, and Local Databases Chevron down icon Chevron up icon Filesystems, Storage, and Local Databases Introduction Saving a file in the device storage Opening a local file from the device storage Displaying the contents of a directory Creating a local SQLite database Uploading a file on a remote server Caching content using the local storage API 4. Working with Audio, Images, and Video Chevron down icon Chevron up icon Working with Audio, Images, and Video Introduction Capturing audio using the device audio recording application Recording audio within your application Playing audio files from the local filesystem or over HTTP Capturing a video using the device video recording application Loading a photograph from the device camera roll/library Applying an effect to an image using canvas Playing a remote video 5. Working with Your Contacts List Chevron down icon Chevron up icon Working with Your Contacts List Introduction Listing all available contacts Displaying the contact information for a specific individual Creating and saving a new contact 6. Hooking into Native Events Chevron down icon Chevron up icon Hooking into Native Events Introduction Pausing your application Resuming your application Displaying the status of the device battery levels Displaying network connection status Creating a custom submenu 7. Working with XUI Chevron down icon Chevron up icon Working with XUI Introduction Getting started with XUI Learning the basics of the library DOM manipulation Working with touch and gesture events Updating element styles Working with remote data and AJAX requests Creating simple tweens and animations 8. Working with the Ionic Framework Chevron down icon Chevron up icon Working with the Ionic Framework Introduction Getting familiar with basics of the library Exploring Ionic commands Exploring the Ionic framework structure Using ngCordova 9. Ionic Framework Development Chevron down icon Chevron up icon Ionic Framework Development Introduction Exploring the UI components Creating a layout Using Ionic and Angular Putting it all together 10. User Interface Development Chevron down icon Chevron up icon User Interface Development Introduction Creating a jQuery Mobile layout Persisting data between jQuery Mobile pages Using jQuery Mobile ThemeRoller 11. Extending PhoneGap with Plugins Chevron down icon Chevron up icon Extending PhoneGap with Plugins Introduction Extending your Cordova Android application with a native plugin Extending your Cordova iOS application with a native plugin The plugin repository 12. Development Tools and Testing Chevron down icon Chevron up icon Development Tools and Testing Introduction Downloading Cordova Using the command line to create a new iOS Cordova project Debugging the iOS Cordova application using Safari Web Inspector Using Android Studio to develop Android Cordova applications Using Adobe Dreamweaver to develop Cordova applications Using the PhoneGap Build service Index Chevron down icon Chevron up icon
Where there is an eBook version of a title available, you can buy it from the book details for that title. Add either the standalone eBook or the eBook and print book bundle to your shopping cart. Your eBook will show in your cart as a product on its own. After completing checkout and payment in the normal way, you will receive your receipt on the screen containing a link to a personalised PDF download file. This link will remain active for 30 days. You can download backup copies of the file by logging in to your account at any time.
If you already have Adobe reader installed, then clicking on the link will download and open the PDF file directly. If you don't, then save the PDF file on your machine and download the Reader to view it.
Please Note: Packt eBooks are non-returnable and non-refundable.
Packt eBook and Licensing When you buy an eBook from Packt Publishing, completing your purchase means you accept the terms of our licence agreement. Please read the full text of the agreement. In it we have tried to balance the need for the ebook to be usable for you the reader with our needs to protect the rights of us as Publishers and of our authors. In summary, the agreement says:
If you want to purchase a video course, eBook or Bundle (Print+eBook) please follow below steps:
Our eBooks are currently available in a variety of formats such as PDF and ePubs. In the future, this may well change with trends and development in technology, but please note that our PDFs are not Adobe eBook Reader format, which has greater restrictions on security.
You will need to use Adobe Reader v9 or later in order to read Packt's PDF eBooks.
What are the benefits of eBooks? Chevron down icon Chevron up iconPackt eBooks are a complete electronic version of the print edition, available in PDF and ePub formats. Every piece of content down to the page numbering is the same. Because we save the costs of printing and shipping the book to you, we are able to offer eBooks at a lower cost than print editions.
When you have purchased an eBook, simply login to your account and click on the link in Your Download Area. We recommend you saving the file to your hard drive before opening it.
For optimal viewing of our eBooks, we recommend you download and install the free Adobe Reader version 9.
