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": {}

See also

• 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