API Reference

A plugin is a package of injected code that allows the Cordova webview within
which the app renders to communicate with the native platform on
which it runs. Plugins provide access to device and platform
functionality that is ordinarily unavailable to web-based apps. All
the main Cordova API features are implemented as plugins, and many
others are available that enable features such as bar code scanners,
NFC communication, or to tailor calendar interfaces. There is a
registry of available plugins.

Plugins comprise a single JavaScript interface along with
corresponding native code libraries for each supported platform. In essence
this hides the various native code implementations behind a common
JavaScript interface.

This section steps through a simple echo plugin that passes a string from
JavaScript to the native platform and back, one that you can use as a
model to build far more complex features. This section discusses the
basic plugin structure and the outward-facing JavaScript interface.
For each corresponding native interface, see the list at the end of
this section.

In addition to these instructions, when preparing to write a plugin it
is best to look over
existing plugins
for guidance.

Application developers use the CLI's plugin add command (discussed
in The Command-Line Interface) to apply a plugin to a project. The
argument to that command is the URL for a git repository containing
the plugin code. This example implements Cordova's Device API:

The plugin repository must feature a top-level plugin.xml manifest
file. There are many ways to configure this file, details for which
are available in the Plugin Specification. This abbreviated version of
the Device plugin provides a simple example to use as a model:

The top-level plugin tag's id attribute uses the same
reverse-domain format to identify the plugin package as the apps to
they're added. The js-module tag specifies the path to the common
JavaScript interface. The platform tag specifies a corresponding
set of native code, for the ios platform in this case. The
config-file tag encapsulates a feature tag that is injected into
the platform-specific config.xml file to make the platform aware of
the additional code library. The header-file and source-file tags
specify the path to the library's component files.

You can use the plugman utility to check whether the plugin installs
correctly for each platform. Install plugman with the following
node command:

$ npm install -g plugman

You need an valid app source directory, such as the top-level www
directory included in a default CLI-generated project as described in
The Command-Line Interface. Make sure the app's index.html home
page reference the name of the plugin's JavaScript interface, as if it
were in the same source directory:

<script src="myplugin.js"></script>

Then run a command such as the following to test whether iOS
dependencies load properly:

The JavaScript provides the front-facing interface, making it perhaps
the most important part of the plugin. You can structure your
plugin's JavaScript however you like, but you need to call
cordova.exec to communicate with the native platform, using the
following syntax:

Look at the last three arguments to the cordova.exec function. The
first calls the Echoservice, a class name. The second requests
the echoaction, a method within that class. The third is an array
of arguments containing the echo string, which is the window.echo
function's the first parameter.

The success callback passed into exec is simply a reference to the
callback function window.echo takes. If the native platform fires
the error callback, it simply calls the success callback and passes it
a default string.

Once you define JavaScript for your plugin, you need to complement it
with at least one native implementation. Details for each platform are
listed below, and each builds on the simple Echo Plugin example above:

Once you develop your plugin, you may want to publish and share it
with the community. You can publish your plugin to the Cordova
registry (based on npmjs) or
to any other npmjs-based registry. Other developers can install it
automatically using either plugman or the Cordova CLI. (For details
on each development path, see Using Plugman to Manage Plugins and The
Command-Line Interface.)

To publish a plugin you need to use the plugman tool and go through
the following steps:

$ plugman adduser # that is if you don't have an account yet
$ plugman publish /path/to/your/plugin