Creating Your Own Cordova Plugin

Although HTML5 offers a wide range of functionality, that functionality is limited to what's provided by the SDK. An application is implemented as a webpage (named index.html by default) that references whatever CSS, JavaScript, images, media files, or other resources are necessary for it to run. The app executes as a WebView within the native application framework. For the web app to interact with various device features the way native apps do, it must also reference a cordova.js file, which provides API bindings. If you want to access other features not provided by the platform SDK, you have to write a plugin. A plugin is a bridge between the WebView the app is running in and the native layer of the platform. Plugins provide a mechanism to call into native APIs that aren't provided with the SDK.

This chapter assumes that you know how to create Cordova plugins for other platforms. For information on creating Cordova plugins, see the Apache Cordova Documentation.

Many of the services available with QNX Neutrino can be accessed through a PPS interface. In the sections that follow, we'll walk through the creation of a simple plugin (com.qnx.demo) that creates a PPS object and writes to it. You can use the same principles to manipulate other PPS objects.

Structure of a plugin

You can place the artifacts of the plugin in any directory structure, as long as you specify the file locations in the plugin.xml file. Here's a typical structure (names in bold represent directories):
  • plugin_name
    • plugin.xml
    • www
      • client.js
    • src
      • blackberry10
        • index.js
        • plugin_name.js
        • other JavaScript or native files, as required (*.js, *.cpp, *.hpp)

The JavaScript part of a plugin must contain, at a minimum, the following resources:

plugin.xml

The plugin.xml file is an XML document in the plugins namespace, http://apache.org/cordova/ns/plugins/1.0. The plugin.xml file contains a top-level plugin element that defines the plugin itself and child elements that define the file structure of the plugin.

You must name this file plugin.xml.

client.js

Considered the client side, this file exports APIs that a Cordova application can call. The APIs in client.js make calls to index.js. The APIs in client.js also connect callback functions to the events that fire the callbacks.

You must name this file client.js.

index.js

Cordova loads index.js and makes it accessible through the cordova.exec() bridge. The client.js file makes calls to the APIs in the index.js file, which in turn makes calls to JNEXT to communicate with the native side.

If your plugin needs to include events, make sure to define these events in index.js. Events are defined inside the _actionMap variable.

You must name this file index.js.

In our example, we need a file to deal with the PPS activities of the plugin. We'll call this file demo.js to reflect the name of the plugin. You can name this file whatever you want, but using the plugin name is standard practice.

Note: Depending on what your plugin needs to do, you might need to create other JavaScript files. In addition, if the native functionality you need isn't available through an existing interface (such as PPS or another plugin), you'll need to write the C/C++ code to provide JavaScript access to that functionality.