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: https://wiki.apache.org/cordova/PluginDiscovery?action=diff&rev1=3&rev2=4 - = Plugin Discovery = + = Plugin Registry = - Cordova plugins can be discovered via a tool called Plugman. Plugman is used by [[CommandLineToolingDesign|cordova-cli]]. + We use [[https://github.com/isaacs/npmjs.org|npmjs.org]]. To set up your own registry. Follow the steps on there. Make sure to set ''secure_rewrites'' to false in your CouchDB config (You can use ''futon'' for that). + = plugin.xml tags = - 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: + To publish a Cordova plugin. One has to specify a couple of things. As per npm, <name> and ''version'' attribute are required. Everything else is optional. <name> has to follow npm's rules (no spaces). + There are new XML tags that are pretty self explanatory: <author>, <description>, <license>, <keywords> (comma separated keywords). They help with search and discovery. - {{{ - 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. + = plugman-registry = - === Where are plugins stored ? === + This is a module used by plugman that relies on npm to talk to the registry. It also creates a package.json based on Cordova's plugin.xml which is required by npm. It stores its configuration and cache in a folder named $HOME/.plugman so that it doesn't interfere with npm's configuration. It implements and maps the following actions: - 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. + * adduser: adds a user to the registry + * publish: creates a package.json based on the plugin.xml and publishes it to the registry + * unpublish: unpublishes package from registry + * search: searches a plugin given some keywords + * fetch: fetches a plugin from cache (if present) or from registry - == List format == + = plugman = - When plugman needs to retrieve information/metadata about a specific plugin it queries the remote source and expects the following response JSON format: + plugman can be pointed at a registry in config.js + plugman has new commands to handle ''adduser'', ''publish'', ''unpublish'', ''search''. One can install a plugin from registry by specifying the plugin_name if that plugin is not already in the Cordova project's plugins directory. - {{{ - - { - "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"; - } - } - ] - } + == Examples == - }}} + {{{$ plugman --plugin plugin_name --project /path/to/project --platform ios}}} + {{{$ plugman --adduser}}} + {{{$ plugman --publish --plugin path/to/plugin}}} + {{{$ plugman --unpublish --plugin plugin[@version]}}} + {{{$ plugman --search --plugin keyword1,keyword2]}}} - === Fields === + = Missing = + npm does not support ''download counts'' or ''popularity'' for packages. We might be able to add that later. - * ''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 -
