Plugin Discovery

Cordova plugins can be discovered via a tool called Plugman. Plugman is used by cordova-cli.

In order to discover plugins, we need to store plugin information/metadata on a remote source. The plugman tool can query that remote source to:

• list all plugins
• query about a specific plugin
• publish/unpublish/update plugins (future)

plugman needs to be properly configured in order to query the remote source. The configuration file is stored in its config/remote.js and has the following format:

exports.remote = {
 url: 'http://plugins.cordova.io',
 query_path: '/cordova_plugins/_design/cordova_plugins/_view/by_name?key=\"%s\"',
 list_path: '/cordova_plugins/_design/cordova_plugins/_view/by_name'
}

Read on if you're interested in finding out how to create your own plugin information source.

Where are plugins stored ?

Plugins are currently stored in Git repositories. Adapters can be written to support different formats (zip, tar.gz etc...). At this time, only Git repositories are supported. The plugin remote source references those Git repositories.

List format

When plugman needs to retrieve information/metadata about a specific plugin it queries the remote source and expects the following response JSON format:

{
   "total_rows":8,
   "offset":0,
   "rows":[
      {
         "id":"713454f9e431d430346baff7d3000b00",
         "key":"BarcodeScanner",
         "value":{
            "_id":"713454f9e431d430346baff7d3000b00",
            "_rev":"2-6059c5c6d0ebd655358d29c9df6e7131",
            "name":"BarcodeScanner",
            "description":"Cross-platform BarcodeScanner for Cordova/PhoneGap",
            "url":"https://github.com/wildabeast/BarcodeScanner"
         }
      },
      {
         "id":"713454f9e431d430346baff7d300254a",
         "key":"ChildBrowser",
         "value":{
            "_id":"713454f9e431d430346baff7d300254a",
            "_rev":"2-47a8fae637f23133cd2c37cbd5be39b3",
            "name":"ChildBrowser",
            "url":"https://github.com/imhotep/ChildBrowser",
            "description":"ChildBrowser plugin"
         }
      },
      {
         "id":"713454f9e431d430346baff7d30019dd",
         "key":"Facebook-Connect",
         "value":{
            "_id":"713454f9e431d430346baff7d30019dd",
            "_rev":"2-bcdc3018717944d2c46092b0e9d3e963",
            "name":"Facebook-Connect",
            "description":"Official plugin for Facebook Connect in Apache Cordova/PhoneGap",
            "url":"https://github.com/phonegap-build/Facebook-Connect"
         }
      },
      {
         "id":"713454f9e431d430346baff7d3001d4b",
         "key":"GAPlugin",
         "value":{
            "_id":"713454f9e431d430346baff7d3001d4b",
            "_rev":"2-6cfbc32830e11accde528f792ad27076",
            "name":"GAPlugin",
            "description":"Google Analytics Plugin",
            "url":"https://github.com/bobeast/GAPlugin"
         }
      },
      {
         "id":"713454f9e431d430346baff7d30042ca",
         "key":"KeychainPlugin",
         "value":{
            "_id":"713454f9e431d430346baff7d30042ca",
            "_rev":"1-d25bb155468a1854949a0bbfde86e0d3",
            "name":"KeychainPlugin",
            "description":"Keychain Plugin for Apache Cordova",
            "url":"https://github.com/shazron/KeychainPlugin.git"
         }
      },
      {
         "id":"713454f9e431d430346baff7d300517b",
         "key":"NFC",
         "value":{
            "_id":"713454f9e431d430346baff7d300517b",
            "_rev":"2-c7d2238309b0b131a3720b82fedf50e1",
            "name":"NFC",
            "description":"Near Field Communication Plugin",
            "url":"https://github.com/chariotsolutions/phonegap-nfc"
         }
      },
      {
         "id":"713454f9e431d430346baff7d300086b",
         "key":"PushPlugin",
         "value":{
            "_id":"713454f9e431d430346baff7d300086b",
            "_rev":"2-07109b721dbceb6b67ea53aed9b6a876",
            "name":"PushPlugin",
            "description":"Push Notification Plugin for iOS and Android",
            "url":"https://github.com/bobeast/PushPlugin"
         }
      },
      {
         "id":"713454f9e431d430346baff7d30043a7",
         "key":"TestflightPlugin",
         "value":{
            "_id":"713454f9e431d430346baff7d30043a7",
            "_rev":"1-d5debc4de98e6451e775c7790623ea02",
            "name":"TestflightPlugin",
            "description":"TestFlight Plugin for Apache Cordova",
            "url":"https://github.com/shazron/TestFlightPlugin.git"
         }
      }
   ]
}

Fields

• total_rows: number of plugins returned

• rows: Array of plugin objects

Each plugin object has a key field and a value field. The key field (String) is the name of the plugin. The value field (Object) contains information/metadata about the plugin. The value object fields are pretty self explanatory.

The id, _id, _rev fields are not required but may be used to publish/unpublish/update plugins in the future.

Query format

When users try to (un)install a plugin by name, plugman queries the remote source for plugin information and handles the (un)install action according to the metadata it gets from the remote source.

The remote source needs to support a lookup request. Plugman will query it and expects the following response format:

{
   "total_rows":8,
   "offset":1,
   "rows":[
      {
         "id":"713454f9e431d430346baff7d300254a",
         "key":"ChildBrowser",
         "value":{
            "_id":"713454f9e431d430346baff7d300254a",
            "_rev":"2-47a8fae637f23133cd2c37cbd5be39b3",
            "name":"ChildBrowser",
            "url":"https://github.com/imhotep/ChildBrowser",
            "description":"ChildBrowser plugin"
         }
      }
   ]
}

The format is the same as the list one except that there should be only one object in the rows Array. The object should contain the queried plugin's information/metadata.

Plugin submission

New plugins can be submitted at http://plugins.cordova.io. Eventually, plugin developers will be able to publish/unpublish plugins to various remotes through the Plugman tool directly.

Discussion/Future

• Response format: The format above is just a proposal and works well with the current version of plugman. It is open for discussion. The important point is that the remote does not have to host plugins, only reference them.
• Naming: what should plugins be named ? What happens when two plugins do the same thing and want the same name ?
• Versioning: Needs support for versions (of plugins as well as cordova).
• Dependencies: Needs support for it