You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by Apache Wiki <wi...@apache.org> on 2013/04/17 09:00:09 UTC
[Cordova Wiki] Update of "PluginTooling" by FilMaj
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.
The "PluginTooling" page has been changed by FilMaj:
http://wiki.apache.org/cordova/PluginTooling?action=diff&rev1=4&rev2=5
+ = Plugin Tooling =
- ## page was copied from PluginDiscovery
- = Plugin Discovery =
- Cordova plugins can be discovered via a tool called Plugman. Plugman is used by [[CommandLineToolingDesign|cordova-cli]].
+ Cordova plugins can be installed and removed via a tool called [[https://git-wip-us.apache.org/asf/repos/cordova-plugman|plugman]], a node.js based tool to install and remove compliant plugins.
+ Based on the Cordova [[PluginDesign|Plugin Design]], a plugin:
- 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:
+ * declares itself as supporting zero or more Cordova-supported platforms
+ * optionally contains web assets, including but not limited to HTML, JavaScript, images, media, and stylesheets
+ * optionally contains platform native code for the Cordova platforms it supports
+ * can be dependent on other plugins
+ == Use Cases ==
- {{{
- 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.
+ * Install a plugin into a cordova project for a platform the plugin supports, which means also satisfying:
+ * Installing a plugin that has one or more plugins as dependencies.
+ * Remove a plugin that I've already added into a cordova project, which means also satisfying:
+ * Removing a plugin that has multiple dependencies, some of which may still be required by other plugins installed into the application, should only remove the dependencies that would no longer be needed, and maintain the dependencies that are still required by other plugins.
+ * When installing a plugin into a cordova project for a platform the plugin does NOT support, the user should see a warning.
+ * When installing one or more plugins, any file collisions that occur should stop the installation and the tooling should error out.
+ * When installing multiple plugins, attempting to install different versions of the same plugin should stop installation and the tooling should error out.
- === 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
-