cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Cordova Wiki] Update of "PluginDiscovery" by AnisKadri
Date Thu, 14 Feb 2013 00:31:38 GMT
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

Mime
View raw message