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