[Cordova Wiki] Update of "PluginDiscovery" by AnisKadri

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "PluginDiscovery" page has been changed by AnisKadri:
http://wiki.apache.org/cordova/PluginDiscovery

New page:
= Plugin Discovery =

Cordova plugins can be discovered via a tool called plugman. Plugman is used by [[cordova-cli|CommandLineToolingDesign]].

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.

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).
- Needs support for dependencies