Example of a native iOS plugin for using PhoneGap 3.0

Posted on July 25, 2013

With the latest release of PhoneGap 3.0 a new plugin architecture is available. Now any plugin can be installed with great tools, such as PhoneGap's CLI or Cordova Plugman.

To benefit from these great new features you may have to consider some important changes, especially for developing custom plugins.

That's why I have created a very simple native iOS plugin for a better understanding of these changes.

Source code

All source of this example is is published at GitHub called "phonegap3-native-ios-plugin". There you will find a detailed installation instruction, too.

Screen shot

Random notes

1) Add a plugin to your project using Cordova CLI.

Example:

cordova plugin add https://github.com/sectore/phonegap3-native-ios-plugin

Or using Phonegap CLI.

Example:

phonegap local plugin add https://github.com/sectore/phonegap3-native-ios-plugin

Or using plugman CLI.

Example:

plugman --platform ios --project ./platforms/ios --plugin https://github.com/sectore/phonegap3-native-ios-plugin

2) Add a plugin definition to the config.xml of your project as follow:

<feature name="MyPlugin">
      <param name="ios-package" value="MyPlugin" />
  </feature>

3) Don't wrap plugin's JS file (located in your-plugin/www) with cordova.define. It will be wrapped as a AMD module automatically.

4) Use the definition of clobbers within the manifest plugin.xml to define the plugin object on window.

For example:

<js-module src="www/MyPlugin.js" name="MyPlugin">
   <clobbers target="myPlugin" />
</js-module>

This will create an Object window.myPlugin to access the plugin globally. So you can reference to the plugin from everywhere in your code. In case of the clobbers definition of MyPlugin example above:

<button onclick="myPlugin.sayHello();">Say Hello to your plugin!</button>

Helpfull links

• Example of a native iOS plugin for using PhoneGap 3.0.: https://github.com/sectore/phonegap3-native-ios-plugin
• PhoneGap documentation: "Plugin Development Guide"
• PhoneGap documentation: "The Command-line Interface"
• PhoneGap documentation: "iOS Plugins"
• Cordova plugman: "plugin.xml - Manifest Format"
• Raymond Camden: "PhoneGap 3.0 Released - Things You Should Know"
• Repositories of core plugins (updated to PhoneGap 3.0): https://git-wip-us.apache.org/repos/asf?s=cordova-plugin

Happy plugin development!

-Jens

Any feedback?