Apache Cordova API Cookbook Cover Image

Note: The book assumes you’ve already had some exposure to Apache Cordova & Adobe PhoneGap. The best way to get that experience is through my Apache Cordova 4 Programming book.

Chapter 1

Chapter 1 contains a brief introduction to Apache Cordova for those that don’t have the background with the framework or want to hear what I have to say about Cordova and Cordova development. It’s not designed to cover everything, that’s done quite well in Apache Cordova 3 Programming. Instead, it provides enough background to get you started if you’ve not worked with Cordova before.

The chapter includes some sample programs that highlight what makes a Cordova application a Cordova application and provides a brief introduction to the device APIs.

Chapter 2

Chapter 2 is all about the Cordova Accelerometer API. The chapter includes a complete description of the Accelerometer API, how it works and how to use it in your Cordova applications. The chapter includes two complete sample applications, one that highlights how to read the accelerometer manually in a Cordova application and another that demonstrates how to use a watch to allow your application to receive periodic accelerometer readings automatically.

Chapter 3

Chapter 3 covers the Camera API; it shows you how to use the Camera API in your Cordova applications to capture images or provide access to pictures stored on your device. For this API, the chapter covers each of the API’s options and provides four sample applications that exercise different aspects of the API in detail.

Chapter 4

The Capture API provides a Cordova application with the ability to capture images, videos and audio recordings using the device Camera and voice recorder applications. Cordova exposes three methods, but a single mechanism for capturing using the available media types. In this chapter you’ll learn how to leverage this API in your applications.

Chapter 5

The Cordova Compass API provides Cordova applications with the ability to measure the orientation of the mobile device running the application. The API is typically used in games and augmented reality applications. The device orientation can be measured in real-time, measurements taken as needed by the application or the application can enable a compass watch that allows the application to automatically be notified when the device’s heading has changed.

The chapter includes two example applications that demonstrate how to implement both types of measurements.

Chapter 6

The Cordova Connection object provides an application with information about the current network connection available on the device (and available to the application).

An application would use the Connection object to help it determine if network connectivity is available as well as the type of connection that is available. If the application had data to upload to or retrieve from a server, knowing whether the connection is available will help the application to determine whether or not to begin the transfer. If an application is working with a large amount of data that it needed to upload to or retrieve from a server, the ability for the application to be able to tell what type of connection is available will allow it to only perform this large update when a less expensive (Wi-Fi) network connection is available.

The chapter includes a sample application that illustrates how to use the Connection API in a Cordova application.

Chapter 7

The Cordova Contacts API provides an applications with an interface it can use to create, locate, read, edit, copy and delete contact records from the device’s native Contacts application. This API interfaces with the native Contacts application provided by the mobile platform and, because of the way the internal API views contact information, there are some quirks that manifest themselves across mobile device platforms.

The chapter includes two complete applications that highlight how the API works.

Chapter 8

The Cordova Device object allows an application to access a limited information about the application and device running a Cordova application. As much as Cordova development is supposed to simplify cross-platform development and third-party HTML5 frameworks are supposed to make that easy, there are still times when an application needs to understand something about the device it’s running on. An application would use this API when enabling or disabling application features or capabilities that are only supported on particular Cordova versions, device model, device platform, device operating system versions and so on.

Chapter 9

The Cordova Events API exposes a specific set of events to a Cordova application developer. These events allow a Cordova application to respond to physical actions such as button presses as well as environmental activities such as battery life and network connection status. Applications register event listeners for specific events that occur on a supported smartphone devices and the Cordova core, or in some cases, specific plugins, notifies the application when the registered event occurs.

An application would use this API to add awareness of specific events to a Cordova application. A game application for example would use Button events to allow a user to use the physical buttons available on some smartphones to be used as action buttons within the game. As shown in Chapter 6, an application can use the network connection awareness events to control when an application attempts to send or receive data with a remote server.

The chapter includes 5 complete applications that illustrate different aspects of the API.

Chapter 10

The Cordova File API provides an application with the methods it needs to interact with the device’s local file system. The API exposes methods an application can use to browse the file system, read, write, copy, move and remove files. An application cannot access just any part of the file system, only the temporary and persistent file storage locations (described below) on a mobile device.

An application would use this API to read and write files on the device file system. An application might use one of the many available storage options for web application to store application data, but developers can also use the file system to persist application settings or application data using the file system, writing text files (in XML or JSON format for example) as needed while the application runs. Additionally, remember that the Camera (Chapter 3) and Capture (Chapter 4) APIs write their files to the file system, applications use the File API to manipulate those files as needed.

Two sample applications are included to help illustrate the features of the File API. The application creates a directory browser application that allows the user to select one of the available storage locations (described in the following section) the read the high-level directory entries for the selected location. The applications can also create a new file, view a file’s contents and remove a file from the file system. The two applications are almost identical, the only difference between the two is in how the applications write to a local file.

Chapter 11

The Cordova Geolocation API allows an application to leverage the GPS capabilities of a mobile device and determine the device’s location on the surface of the Earth. Using this API, an application can either manually check the device’s current position or it can create a location watch that will cause the application to be periodically notified of the device’s physical location.

The Geolocation API is implemented in the same manner as the Accelerometer (Chapter 2) and Compass (Chapter 5) APIs. All three APIs expose a way to query the particular metric individually or by defining a watch and measuring the metric repeatedly over time. The differences between the implementations for the different APIs is in what options are available to control the measurement and what data is returned to the Cordova application through the appropriate success callback function.

An application would use this API to capture the device’s location and use the associated data with other data elements in the application (such as recording where the device was when a particular piece of data was entered into the application) or passed to a server for geo-fencing purposes.

Chapter 12

The Cordova Globalization API exposes methods an application can use to help identify the device’s current configuration for language plus the display and conversion of dates, numbers and currency values.

Many mobile applications are initially created with content in English, but in order to address a wider potential audience for the application, the developer may also provide content within the application in different languages. In order to do that, the application must be able to determine what language the user has configured on the device and switch in the appropriate content if available.

Additionally, any application that works with and displays decimal numbers, currencies, percentages, date and time values must be able to format those values as appropriate based upon the locale the user has configured on her device. The Globalization API exposes the methods a developer needs in order to ensure that content is displayed correctly within the application.

For the sample applications for this chapter, I took a different approach from all of the other applications shown in this book. Instead of creating multiple sample applications that demonstrate the operation of each of the API’s methods, I created a quick demo application then a big application that demonstrates everything.

Chapter 13

The InAppBrowser is a more recent edition to the Cordova API. It allows a web application to load content into a separate window. Originally created as independent Cordova plugins called ChildBrowser for Android and iOS, it was added to the Cordova project as InAppBrowser then expanded to support other mobile device platforms.

Chapter 14

The Cordova Media API provides applications with the ability to record and play audio files from within a Cordova application. With this API, there is some overlap with the capabilities of the Capture API described in Chapter 3. The Capture API allows you to only record audio files using the built-in Voice Recorder application, while the Media API will play and record audio files from directly within the Cordova application’s UI. The documentation for the Media API indicates that the API doesn’t follow the capture standard and warns developers that future development will be around the Capture API.

That being said, there’s still some usefulness for this API. Even though the Capture API allows you to capture audio files, duplicating the same functionality provided in the Media API, the Capture API doesn’t provide a mechanism to play audio files, so you’ll need the Media API to do that.

An application would use this API to play audio files while the application is running. This is primarily used by games; used as a mechanism for playing a soundtrack and in-game sounds as the game is played. You can also use this API to record voice notes and automatically attach them to some information in a Customer Relationship Management (CRM) application for example.

Sample applications are included that illustrate how to play audio files using this API. I ran into a lot of cross-platform issues with this particular application, so there’s a lot of good content in the chapter that describes everything. Another application highlighted in the chapter illustrates how to record audio files using the API.

Chapter 15

The Cordova Notification API provides methods that allow an application to provide feedback to a user visually (through pop-up alerts) and through tactile or audible feedback. The methods supported by this API are:

  • notification.alert
  • notification.beep
  • notification.confirm
  • notification.prompt
  • notification.vibrate

An application would use this API to interact with the user outside of the application’s main screens. Alert is used to draw the user’s attention to something beyond the ordinary. Beep and Vibrate are used to provide some extra feedback about something’s that happened or is about to happen.

Chapter 16

The Cordova Splashscreen API simplifies the process of displaying an application splash screen. An application would use this API to display a custom splash screen during application launch, but also as the application begins some time consuming operation or as the application switches between modes.

The API really only targets iOS and the default iOS Cordova project template already includes standard Cordova graphics for the application splash screen. You can use this API without modification in iOS applications created by the Cordova CLI. After I show you how to use the API, I show how to replace the default splash screen graphics provided by the Cordova project with your own. For iOS and other platforms, implementing a splash screen is a more complicated process.