Although HTML5
offers a wide range of functionality, that functionality is limited to what's provided
by the SDK. There are a number of plugins available, but many of them are meant to be
used on a mobile device, such as phone. You might find it useful to create your own
plugins—especially if you want to access native platform functionality.
An app 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 HTML5 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.
It's presumed you know how to create Cordova plugins. For information about creating
Cordova plugins, see the Apache Cordova
Documentation.
Many of the services available with Apps and Media can
be accessed through a PPS interface. In the sections that follow, a simple plugin
(com.qnx.demo) creates a Persistent Publish/Subscribe(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 (plugin_name, www,
src, and blackberry10 are directory names):
- plugin_name
- plugin.xml
- www
- 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. In this
example, the file is named demo.js to reflect the name of the
plugin. However, you can name this file whatever you want, but using the plugin name
is a 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 require isn't available
through an existing interface (such as a PPS object or another plugin), you must
write the C/C++ code to provide JavaScript access to that functionality.