http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/guide/support/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/support/index.md b/www/docs/en/dev/guide/support/index.md new file mode 100644 index 0000000..14292e1 --- /dev/null +++ b/www/docs/en/dev/guide/support/index.md @@ -0,0 +1,335 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: Platform Support +--- + +# Platform Support + +The following shows the set of development tools and device APIs +available for each mobile platform. The device APIs listed here are provided by +the core plugins, additional APIs are available via +[third-party plugins](http://plugins.cordova.io). Column headers display the +CLI's shorthand names. + +<!-- START HTML --> + +<table class="compat" width="100%"> + +<thead> + <tr> + <th></td> + <th><tt>amazon-fireos</tt></th> + <th><tt>android</tt></th> + <th><tt>blackberry10</tt></th> + <th><tt>Firefox OS</tt></th> + <th><tt>ios</tt></th> + <th><tt>Ubuntu</tt></th> + <th><tt>wp8</tt><br/>(Windows Phone 8)</th> + <th><tt>windows</tt><br/>(8.0, 8.1, 10,<br/>Phone 8.1)</th> + </tr> + +</thead> + +<tbody> + <tr> + <th><a href="../cli/index.html">cordova<br/>CLI</a></th> + <td data-col="amazon-fireos" class="y">Mac, Windows, Linux</td> + <td data-col="android" class="y">Mac, Windows, Linux</td> + <td data-col="blackberry10" class="y">Mac, Windows</td> + <td data-col="firefoxos" class="y">Mac, Windows, Linux</td> + <td data-col="ios" class="y">Mac</td> + <td data-col="ubuntu" class="y">Ubuntu</td> + <td data-col="winphone8" class="y">Windows</td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="../hybrid/webviews/index.html">Embedded<br/>WebView</a></th> + <td data-col="amazon-fireos" class="y"><a href="../platforms/amazonfireos/webview.html">(see details)</a></td> + <td data-col="android" class="y"><a href="../platforms/android/webview.html">(see details)</a></td> + <td data-col="blackberry10" class="n"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"><a href="../platforms/ios/webview.html">(see details)</a></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="n"></td> + <td data-col="win8" class="n"></td> + </tr> + + <tr> + <th><a href="../hybrid/plugins/index.html">Plug-in<br/>Interface</a></th> + <td data-col="amazon-fireos" class="y"><a href="../platforms/amazonfireos/plugin.html">(see details)</a></td> + <td data-col="android" class="y"><a href="../platforms/android/plugin.html">(see details)</a></td> + <td data-col="blackberry10" class="y"><a href="../platforms/blackberry10/plugin.html">(see details)</a></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"><a href="../platforms/ios/plugin.html">(see details)</a></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"><a href="../platforms/wp8/plugin.html">(see details)</a></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th></th> + <th colspan="20">Platform APIs</th> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-device-motion";>Accelerometer</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="y"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-battery-status";>BatteryStatus</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="y"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="n"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y">* Windows Phone 8.1 only</td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-camera";>Camera</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="y"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-media-capture";>Capture</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-device-orientation";>Compass</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y">(3GS+)</td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-network-information";>Connection</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-contacts";>Contacts</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="y"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="p">partially</td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-device";>Device</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="y"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="../../cordova/events/events.html">Events</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-file";>File</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-file-transfer";>File Transfer</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y">* Do not support onprogress nor abort</td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="n"></td> + <td data-col="winphone8" class="y">* Do not support onprogress nor abort</td> + <td data-col="win8" class="y">* Do not support onprogress nor abort</td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-geolocation";>Geolocation</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="y"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-globalization";>Globalization</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-inappbrowser";>InAppBrowser</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="p">uses iframe</td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-media";>Media</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-dialogs";>Notification</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-splashscreen";>Splashscreen</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y"></td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-statusbar";>Status Bar</a></th> + <td data-col="amazon-fireos" class="n"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="n"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="n"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y">Windows Phone 8.1 only</td> + </tr> + + <tr> + <th><a href="../../cordova/storage/storage.html">Storage</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="n"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="y"></td> + <td data-col="winphone8" class="y">localStorage & indexedDB</td> + <td data-col="win8" class="y">localStorage & indexedDB</td> + </tr> + + <tr> + <th><a href="https://www.npmjs.com/package/cordova-plugin-vibration";>Vibration</a></th> + <td data-col="amazon-fireos" class="y"></td> + <td data-col="android" class="y"></td> + <td data-col="blackberry10" class="y"></td> + <td data-col="firefoxos" class="y"></td> + <td data-col="ios" class="y"></td> + <td data-col="ubuntu" class="n"></td> + <td data-col="winphone8" class="y"></td> + <td data-col="win8" class="y">* Windows Phone 8.1 only</td> + </tr> + +</tbody> +</table> + +<!-- END HTML -->
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/index.md b/www/docs/en/dev/index.md new file mode 100644 index 0000000..aa15fa2 --- /dev/null +++ b/www/docs/en/dev/index.md @@ -0,0 +1,105 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: Guides +--- + +<div id="home"> + + <h1>Guides</h1> + <ul> + <li> + <h2><a href="guide/overview/index.html">Overview</a></h2> + <span>Start here if you are new to Cordova. Includes installation and next steps.</span> + </li> + <li> + <h2><a href="guide/support/index.html">Platform Support</a></h2> + <span>Compatibility table for all major features.</span> + </li> + <li> + <h2><a href="guide/cli/index.html">The Command-Line Interface</a></h2> + <span>Create, build, and deploy from the command-line.</span> + </li> + <li> + <h2><a href="guide/platforms/index.html">Platform Guides</a></h2> + <span>Set up each platform SDK and update projects.</span> + </li> + <li> + <h2><a href="plugin_ref/plugman.html">Using Plugman to Manage Plugins</a></h2> + <span>Manage plugins without the CLI when using the platform-centered workflow.</span> + </li> + <li> + <h2><a href="config_ref/index.html">The config.xml File</a></h2> + <span>Customize your app's features.</span> + </li> + <li> + <h2><a href="config_ref/images.html">Icons and Splash Screens</a></h2> + <span>Customize your app's displaying images.</span> + </li> + <li> + <h2><a href="guide/hybrid/webviews/index.html">Embedding WebViews</a></h2> + <span>Implement the Cordova WebView in your native project.</span> + </li> + <li> + <h2><a href="guide/hybrid/plugins/index.html">Plugin Development Guide</a></h2> + <span>Develop your own plugin.</span> + </li> + <li> + <h2><a href="guide/appdev/privacy/index.html">Privacy Guide</a></h2> + <span>Learn about important mobile privacy issues.</span> + </li> + <li> + <h2><a href="guide/appdev/security/index.html">Security Guide</a></h2> + <span>Information and tips for building a secure application.</span> + </li> + <li> + <h2><a href="platform_plugin_versioning_ref/index.html">Platforms and Plugins Version Management</a></h2> + <span>Save and Restore your CLI projects to a known state without hassle.</span> + </li> + <li> + <h2><a href="guide/appdev/whitelist/index.html">Whitelist Guide</a></h2> + <span>Grant an application access to external resources.</span> + </li> + <li> + <h2><a href="cordova/storage/storage.html">Storage</a></h2> + <span>An overview of native storage options.</span> + </li> + <li> + <h2><a href="guide/appdev/hooks/index.html">Hooks Guide</a></h2> + <span>Extend default Cordova functionality by adding custom scripts.</span> + </li> + <li> + <h2><a href="guide/next/index.html">Next Steps</a></h2> + <span>A look at topics that new Cordova developers will encounter.</span> + </li> + </ul> + + <h1>API Reference</h1> + <ul> + <li> + <h2><a href="cordova/events/events.html">Events</a></h2> + <span>Hook into native events through JavaScript.</span> + </li> + <li> + <h2><a href="cordova/plugins/pluginapis.html">Plugin APIs</a></h2> + <span>Discover what Cordova plugins are available to use in your project.</span> + </li> + </ul> + +</div> http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/page_index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/page_index.md b/www/docs/en/dev/page_index.md new file mode 100644 index 0000000..24ec817 --- /dev/null +++ b/www/docs/en/dev/page_index.md @@ -0,0 +1,4 @@ +--- +title: Keyword Index +--- +{% include docs_index.html %} http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/platform_plugin_versioning_ref/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md new file mode 100644 index 0000000..3e2c6f6 --- /dev/null +++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md @@ -0,0 +1,160 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: Platforms and Plugins Version Management +--- + +# Platforms and Plugins Version Management +From version 4.3.0 onwards, Cordova provides the ability to save and restore platforms and plugins. + +This feature allows developers to save and restore their app to a known state without having to check in all of the platform and plugin source code. + +The 'save' command stores details about the app's platform and plugin versions in config.xml. +The 'restore' step happens automatically when a **'cordova prepare'** is issued, making use of information previously saved in the config.xml file. + +One scenario where save/restore capabilities come in handy is in large teams that work on an app, with each team member focusing on a platform or plugin. This feature makes it easier to share the project and reduce the amount of redundant code that is checked in the repository. + + +## Platform Versioning + +### Saving platforms +To save a platform, you issue the following command : + + $ cordova platform add <platform[@<version>] | directory | git_url> --save + +After running the above command, the resulting config.xml looks like : + + <?xml version='1.0' encoding='utf-8'?> + ... + <engine name="android" spec="~4.0.0" /> + ... + </xml> + + +Some examples : + + * **'cordova platform add android --save'** => retrieves the pinned version of the android platform, adds it to the project and then updates config.xml. + * **'cordova platform add [email protected] --save'** => retrieves the android platform, version 3.7.0 from npm, adds it to the project and then updates config.xml. + * **'cordova platform add android@https://github.com/apache/cordova-android.gitâ --save'** => clones the specified cordova-android git repository, adds the android platform to the project, then updates config.xml and point its version to the specified git-url. + * **'cordova platform add C:/path/to/android/platform --save'** => retrieves the android platform from the specified directory, adds it to the project, then updates config.xml and point to the directory. + +### Mass saving platforms on an existing project +The '--save' flag described above is only useful when you remember to use it during the platform addition. +If you have a pre-existing project and you want to save all the currently added platforms in your project, you can use : + + $ cordova platform save + + +### Updating / Removing platforms +It is also possible to update/delete from config.xml during the commands 'cordova platform update' and 'cordova platform remove' : + + $ cordova platform update <platform[@<version>] | directory | git_url> --save + $ cordova platform remove <platform> --save +Some examples : + + * **'cordova platform update android --save'** => In addition to updating the android platform to the pinned version, update config.xml entry + * **'cordova platform update [email protected] --save'** => In addition to updating the android platform to version 3.8.0, update config.xml entry + * **'cordova platform update /path/to/android/platform --save'** => In addition to updating the android platform to version in the folder, update config.xml entry + * **'cordova platform remove android --save'** => Removes the android platform from the project and deletes its entry from config.xml. + + +### Restoring platforms + +Platforms are automatically restored from config.xml when the **'cordova prepare'** command is run. + +If you add a platform without specifying a version/folder/git_url, the version to install is taken from config.xml, **if found**. + +Example: + +Suppose your config.xml file contains the following entry: + + <?xml version='1.0' encoding='utf-8'?> + ... + <engine name="android" spec="3.7.0" /> + ... + </xml> + +If you run the command **'cordova platform add android'** (no version/folder/git_url specified), the platform '[email protected]' (as retrieved from config.xml) will be installed. + + + +--- + +## Plugin Versioning +_(The plugin commands are a mirror of the platform commands)_ + +### Saving plugins +To save a plugin, you issue the following command : + + $ cordova plugin add <plugin[@<version>] | directory | git_url> --save + +After running the above command, the resulting config.xml looks like : + + <?xml version='1.0' encoding='utf-8'?> + ... + <plugin name="cordova-plugin-console" spec="~1.0.0" /> + ... + </xml> + + +Some examples : + + * **'cordova plugin add cordova-plugin-console --save'** => retrieves the pinned version of the console plugin, adds it to the project and then updates config.xml. + * **'cordova plugin add [email protected] --save'** => retrieves the android plugin, version 0.2.13 from npm, adds it to the project and then updates config.xml. + * **'cordova plugin add https://github.com/apache/cordova-plugin-console.git --save'** => clones the specified console plugin git repository, adds the console plugin to the project, then updates config.xml and point its version to the specified git-url. + * **'cordova plugin add C:/path/to/console/plugin --save'** => retrieves the console plugin from the specified directory, adds it to the project, then updates config.xml and point to the directory. + +### Mass saving plugins on an existing project +The '--save' flag described above is only useful when you remember to use it during the plugin addition. +If you have a pre-existing project and you want to save all currently added plugins in the project, you can use : + + $ cordova plugin save + + +### Updating / Removing plugins +It is also possible to update/delete from config.xml during the commands 'cordova plugin update' and 'cordova plugin remove' : + + $ cordova plugin update <plugin[@<version>] | directory | git_url> --save + $ cordova plugin remove <plugin> --save +Some examples : + + * **'cordova plugin update cordova-plugin-console --save'** => In addition to updating the console plugin to the pinned version, update config.xml entry + * **'cordova plugin update [email protected] --save'** => In addition to updating the android plugin to version 3.8.0, update config.xml entry + * **'cordova plugin update /path/to/console/plugin --save'** => In addition to updating the console plugin to version in the folder, update config.xml entry + * **'cordova plugin remove cordova-plugin-console --save'** => Removes the console plugin from the project and deletes its entry from config.xml. + + +### Restoring plugins + +Plugins are automatically restored from config.xml when the **'cordova prepare'** command is run. + +If you add a plugin without specifying a version/folder/git_url, the version to be installed is taken from config.xml, **if found**. + +Example: + +Suppose your config.xml file contains the following entry: + + <?xml version='1.0' encoding='utf-8'?> + ... + <plugin name="cordova-plugin-console" spec="0.2.11" /> + ... + </ xml> + +If you run the command **'cordova plugin add cordova-plugin-console'** (no version/folder/git_url specified), the plugin '[email protected]' (as retrieved from config.xml) will be installed. + http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/plugin_ref/plugman.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/plugin_ref/plugman.md b/www/docs/en/dev/plugin_ref/plugman.md new file mode 100644 index 0000000..eb1f856 --- /dev/null +++ b/www/docs/en/dev/plugin_ref/plugman.md @@ -0,0 +1,223 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: Using Plugman to Manage Plugins +--- + +# Using Plugman to Manage Plugins + +From version 3.0 onward, Cordova implements all device APIs as +plugins, and leaves them disabled by default. It also supports two +different ways to add and remove plugins, depending on your choice of +workflow discussed in the [Overview](../guide/overview/index.html): + +- If you use a cross-platform workflow, you use the `cordova` CLI + utility to add plugins, as described in [The Command-Line Interface](../guide/cli/index.html). + The CLI modifies plugins for all specified platforms at once. + +- If you use a platform-centered workflow, you use a lower-level + [Plugman](https://github.com/apache/cordova-plugman/) command-line + interface, separately for each targeted platform. + +This section details the Plugman utility. For more information on +consuming Plugman as a node module or modifying the source code, see +[the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md). + +## Installing Plugman + +To install plugman, you must have [node](http://nodejs.org/) installed +on your machine. Then you can run the following command from anywhere +in your environment to install plugman globally, so that it is +available from any directory: + + $ npm install -g plugman + +You must have also have `git` on your `PATH` to be able to install plugins directly from remote git URLs. + +__TIP__: If you find that after installing plugman with `npm` you are +still unable to run any `plugman` commands, make sure that you have +added the `/npm/` directory into your `PATH`. + +__NOTE__: You can skip this step if you don't want to pollute your +global `npm` namespace by installing Plugman globally. If this is the +case, then when you create a Cordova project with the shell tools, +there will be a `node_modules` directory inside your project which +contains Plugman. Since you did not install globally, you need to +invoke `node` for each Plugman command, for example `node +./node_modules/plugman/main.js -version`. The rest of this guide +assumes you have installed Plugman globally, meaning you can invoke it +with just `plugman`. + +## Create a Cordova Project + +Before you can use Plugman, you must create a Cordova project. You can do this with either the Command-line Interface or with +the lower level shell scripts. Instructions for using the shell scripts to create your project are located in the various "Command-line Tools" guides +listed on the [Platform Guides](../guide/platforms/index.html) page. + +## Adding a Plugin + +Once you have installed Plugman and have created a Cordova project, you can start adding plugins to the platform with: + + $ plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]] + +Using minimum parameters, this command installs a plugin into a cordova project. You must specify a platform and cordova project location for that platform. You also must specify a plugin, with the different `--plugin` parameter forms being: + + * `name`: The directory name where the plugin contents exist. This must be an existing directory under the `--plugins_dir` path (see below for more info) or a plugin in the Cordova registry. + * `url`: A URL starting with https:// or git://, pointing to a valid git repository that is clonable and contains a `plugin.xml` file. The contents of this repository would be copied into the `--plugins_dir`. + * `path`: A path to a directory containing a valid plugin which includes a `plugin.xml` file. This path's contents will be copied into the `--plugins_dir`. + +Other parameters: + +* `--plugins_dir` defaults to `<project>/cordova/plugins`, but can be any directory containing a subdirectory for each fetched plugin. +* `--www` defaults to the project's `www` folder location, but can be any directory that is to be used as cordova project application web assets. +* `--variable` allows to specify certain variables at install time, necessary for certain plugins requiring API keys or other custom, user-defined parameters. Please see the [plugin specification](plugin_ref_spec.md.html#Plugin%20Specification) for more information. + +## Remove a Plugin + +To uninstall a plugin, you simply pass the `--uninstall` flag and provide the plugin ID. + + $ plugman --uninstall --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>] + + +## Help Commands + +Plugman features a global help command which may help you if you get stuck or are experiencing problems. It will display +a list of all available Plugman commands and their syntax: + + plugman -help + plugman # same as above + + **NOTE**: `plugman -help` may show some additional registry-related commands. These commands are for plugin developers and may not be implemented on third-party plugin registries. + + +You can also append the `--debug|-d` flag to any Plugman command to run that command in verbose mode, which will display +any internal debugging messages as they are emitted and may help you track down problems like missing files. + + # Adding Android battery-status plugin to "myProject": + plugman -d --platform android --project myProject --plugin cordova-plugin-battery-status + +Finally, you can use the `--version|-v` flag to see which version of Plugman you are using. + + plugman -v + +## Registry Actions + +There are a number of plugman commands that can be used for interacting with the [Plugin registry](http://plugins.cordova.io). +Please note that these registry commands are specific to the _plugins.cordova.io_ plugin registry and may not be implemented by +third-party plugin registries. + +### Searching for a Plugin + +You can use Plugman to search the [Plugin registry](http://plugins.cordova.io) for plugin id's that match the given space separated list of keywords. + + plugman search <plugin keywords> + +### Changing the Plugin Registry + +You can get or set the URL of the current plugin registry that plugman is using. Generally you should leave this set at http://registry.cordova.io unless you want to use a third party plugin registry. + + plugman config set registry <url-to-registry> + plugman config get registry + +### Get Plugin Information + +You can get information about any specific plugin stored in the plugin repository with: + + plugman info <id> + +This will contact the plugin registry and fetch information such as the plugin's version number. + +## Installing Core Plugins + +The examples below show how to add plugins as needed so that any +Cordova APIs you use in your project still work after you upgrade to +version 3.0. For each command, you need to select the target +platform, and reference the platform's project directory. + +* cordova-plugin-battery-status + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-battery-status` + +* cordova-plugin-camera + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-camera` + +* cordova-plugin-console + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-console` + +* cordova-plugin-contacts + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-contacts` + +* cordova-plugin-device + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device` + +* cordova-plugin-device-motion (accelerometer) + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device-motion` + +* cordova-plugin-device-orientation (compass) + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-device-orientation` + +* cordova-plugin-dialogs + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-dialogs` + +* cordova-plugin-file + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-file` + +* cordova-plugin-file-transfer + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-file-transfer` + +* cordova-plugin-geolocation + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-geolocation` + +* cordova-plugin-globalization + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-globalization` + +* cordova-plugin-inappbrowser + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-inappbrowser` + +* cordova-plugin-media + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-media` + +* cordova-plugin-media-capture + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-media-capture` + +* cordova-plugin-network-information + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-network-information` + +* cordova-plugin-splashscreen + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-splashscreen` + +* cordova-plugin-vibration + + `plugman --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin cordova-plugin-vibration` http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/dev/plugin_ref/spec.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/plugin_ref/spec.md b/www/docs/en/dev/plugin_ref/spec.md new file mode 100644 index 0000000..ce86297 --- /dev/null +++ b/www/docs/en/dev/plugin_ref/spec.md @@ -0,0 +1,716 @@ +--- +license: > + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +title: Plugin Specification +--- + +# Plugin Specification + +The `plugin.xml` file is an XML document in the `plugins` namespace: +`http://apache.org/cordova/ns/plugins/1.0`. It contains a top-level +`plugin` element that defines the plugin, and children that define the +structure of the plugin. + +A sample plugin element: + + <?xml version="1.0" encoding="UTF-8"?> + <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"; + xmlns:android="http://schemas.android.com/apk/res/android"; + id="com.alunny.foo" + version="1.0.2"> + +## _plugin_ Element + +The `plugin` element is the plugin manifest's top-level element. It +features the following attributes: + +* `xmlns` (required): + The plugin namespace, `http://apache.org/cordova/ns/plugins/1.0`. If + the document contains XML from other namespaces, such as tags to be + added to the `AndroidManifest.xml` file, those namespaces should + also be included in the top-level element. + +* `id` (required): + A reverse-domain style identifier for the plugin, such as + `com.alunny.foo` + +* `version` (required): + A version number for the plugin, that matches the following + major-minor-patch style regular expression: + + ^\d+[.]\d+[.]\d+$ + +## _engines_ and _engine_ Elements + +The child elements of the `<engines>` element specify versions of +Apache Cordova-based frameworks that this plugin supports. An example: + + <engines> + <engine name="cordova" version="1.7.0" /> + <engine name="cordova" version="1.8.1" /> + <engine name="worklight" version="1.0.0" platform="android" scriptSrc="worklight_version"/> + </engines> + +Similar to the `<plugin>` element's `version` attribute, the specified +version string should match a major-minor-patch string conforming to +the regular expression: + + ^\d+[.]\d+[.]\d+$ + +Engine elements may also specify fuzzy matches to avoid repetition, +and to reduce maintenance when the underlying platform is updated. +Tools should support a minimum of `>`, `>=`, `<` and `<=`, for +example: + + <engines> + <engine name="cordova" version=">=1.7.0" /> + <engine name="cordova" version="<1.8.1" /> + </engines> + +The `<engine>` tags also has default support for all of the main platforms Cordova exists on. +Specifying the `cordova` engine tag means that all versions of Cordova on any platform must +satisfy the engine version attribute. You may also list specific platforms and their versions +in order to override the catch-all `cordova` engine: + + <engines> + <engine name="cordova" version=">=1.7.0" /> + <engine name="cordova-android" version=">=1.8.0" /> + <engine name="cordova-ios" version=">=1.7.1" /> + </engines> + +Here's a list of the default engines that the `<engine>` tag supports: + +* `cordova` +* `cordova-plugman` +* `cordova-amazon-fireos` +* `cordova-android` +* `cordova-ios` +* `cordova-blackberry10` +* `cordova-wp8` +* `cordova-windows8` +* `android-sdk` // returns the highest Android api level installed +* `apple-xcode` // returns the xcode version +* `apple-ios` // returns the highest iOS version installed +* `apple-osx` // returns the OSX version +* `blackberry-ndk` // returns the native blackberry SDK version + +Specifying custom Apache Cordova-based frameworks should be listed under the engine tag like so: + + <engines> + <engine name="my_custom_framework" version="1.0.0" platform="android" scriptSrc="path_to_my_custom_framework_version"/> + <engine name="another_framework" version=">0.2.0" platform="ios|android" scriptSrc="path_to_another_framework_version"/> + <engine name="even_more_framework" version=">=2.2.0" platform="*" scriptSrc="path_to_even_more_framework_version"/> + </engines> + +A custom Apache Cordova-based framework requires that an engine element includes the following attributes: +`name`, `version`, `scriptSrc`, and `platform`. + +* `name` (required): A human-readable name for your custom framework. + +* `version` (required): The version that your framework must have in order to install. + +* `scriptSrc` (required): The script file that tells plugman what version of the custom framework is. +Ideally, this file should be within the top level directory of your plugin directory. + +* `platform` (required): Which platforms that your framework supports. You may use the wildcard `*` +to say supported for all platforms, specify multiple with a pipe character like `android|ios|blackberry10` +or just a single platform like `android`. + +plugman aborts with a non-zero code for any plugin whose target +project does not meet the engine's constraints. + +If no `<engine>` tags are specified, plugman attempts to install into +the specified cordova project directory blindly. + +## _name_ Element + +A human-readable name for the plugin, whose text content contains the +name of the plugin. For example: + + <name>Foo</name> + +This element does not (yet) handle localization. + +## _description_ Element + +A human-readable description for the plugin. The text content of the element contains +the description of the plugin. An example: + + <description>Foo plugin description</description> + +This element does not (yet) handle localization. + +## _author_ Element + +Plugin author name. The text content of the element contains +the name of the plugin author. An example: + + <author>Foo plugin description</author> + +## _keywords_ Element + +Plugin keywords. The text content of the element contains comma separated keywords to describe the plugin. An example: + + <keywords>foo,bar</keywords> + +## _license_ Element + +Plugin license. The text content of the element contains the plugin license. An example: + + <license>Apache 2.0 License</license> + +## _asset_ Element + +One or more elements listing the files or directories to be copied +into a Cordova app's `www` directory. Examples: + + <!-- a single file, to be copied in the root directory --> + <asset src="www/foo.js" target="foo.js" /> + <!-- a directory, also to be copied in the root directory --> + <asset src="www/foo" target="foo" /> + +All `<asset>` tags require both `src` and `target` attributes. +Web-only plugins contains mostly `<asset>` elements. Any `<asset>` +elements that are nested within `<platform>` elements specify +platform-specific web assets, as described below. Attributes include: + +* `src` (required): + Where the file or directory is located in the plugin package, + relative to the `plugin.xml` document. If a file does not exist at + the specified `src` location, plugman stops and reverses the + installation process, issues a notification about the conflict, and + exits with a non-zero code. + +* `target` (required): + + Where the file or directory should be located in the Cordova app, + relative to the `www` directory. + Assets can be targeted to subdirectories, for example: + + <asset src="www/new-foo.js" target="js/experimental/foo.js" /> + + creates the `js/experimental` directory within the `www` directory, + unless already present, then copies the `new-foo.js` file and + renames it `foo.js`. If a file already exists at the target + location, plugman stops and reverses the installation process, + issues a notification about the conflict, and exits with a non-zero + code. + +## _js-module_ Element + +Most plugins include one or more JavaScript files. Each `<js-module>` +tag corresponds to a JavaScript file, and prevents the plugin's users +from having to add a `<script>` tag for each file. While `<asset>` +tags simply copy a file from the plugin subdirectory into `www`, +`<js-module>` tags are much more sophisticated. They look like this: + + <js-module src="socket.js" name="Socket"> + <clobbers target="chrome.socket" /> + </js-module> + +When installing a plugin with the example above, `socket.js` is copied +to `www/plugins/my.plugin.id/socket.js`, and added as an entry to +`www/cordova_plugins.js`. At load time, code in `cordova.js` uses XHR +to read each file and inject a `<script>` tag into HTML. It adds a +mapping to clobber or merge as appropriate, as described below. + +_Do not_ wrap the file with `cordova.define`, as it is added +automatically. The module is wrapped in a closure, with `module`, +`exports`, and `require` in scope, as is normal for AMD modules. + +Details for the `<js-module>` tag: + +* The `src` references a file in the plugin directory relative to the + `plugin.xml` file. + +* The `name` provides the last part of the module name. It can + generally be whatever you like, and it only matters if you want to + use `cordova.require` to import other parts of your plugins in your + JavaScript code. The module name for a `<js-module>` is your + plugin's `id` followed by the value of `name`. For the example + above, with an `id` of `chrome.socket`, the module name is + `chrome.socket.Socket`. + +* Three tags are allowed within `<js-module>`: + + - `<clobbers target="some.value"/>` indicates that the + `module.exports` is inserted into the `window` object as + `window.some.value`. You can have as many `<clobbers>` as you + like. Any object not available on `window` is created. + + - `<merges target="some.value"/>` indicates that the module + should be merged with any existing value at `window.some.value`. + If any key already exists, the module's version overrides the + original. You can have as many `<merges>` as you like. Any + object not available on `window` is created. + + - `<runs/>` means that your code should be specified with + `cordova.require`, but not installed on the `window` + object. This is useful when initializing the module, attaching + event handlers or otherwise. You can only have up to one + `<runs/>` tag. Note that including a `<runs/>` with + `<clobbers/>` or `<merges/>` is redundant, since they also + `cordova.require` your module. + + - An empty `<js-module>` still loads and can be accessed in other + modules via `cordova.require`. + +If `src` does not resolve to an existing file, plugman stops and +reverses the installation, issues a notification of the problem, and +exits with a non-zero code. + +Nesting `<js-module>` elements within `<platform>` declares +platform-specific JavaScript module bindings. + +## _dependency_ Element + +The `<dependency>` tag allows you to specify other plugins on which the +current plugin depends. While future versions will access them from +plugin repositories, in the short term plugins are directly referenced +as URLs by `<dependency>` tags. They are formatted as follows: + + <dependency id="com.plugin.id" url="https://github.com/myuser/someplugin"; commit="428931ada3891801" subdir="some/path/here" /> + +* `id`: provides the ID of the plugin. It should be globally unique, + and expressed in reverse-domain style. While neither of these + restrictions is currently enforced, they may be in the future. + +* `url`: A URL for the plugin. This should reference a git repository, + which plugman attempts to clone. + +* `commit`: This is any git reference understood by `git checkout`: a + branch or tag name (e.g., `master`, `0.3.1`), or a commit hash (e.g., + `975ddb228af811dd8bb37ed1dfd092a3d05295f9`). + +* `subdir`: Specifies that the targeted plugin dependency exists as a + subdirectory of the git repository. This is helpful because it + allows the repository to contain several related plugins, each + specified individually. + +In the future, version constraints will be introduced, and a plugin +repository will exist to support fetching by name instead of explicit +URLs. + +### Relative Dependency Paths + +If you set the `url` of a `<dependency>` tag to `"."` and provide a +`subdir`, the dependent plugin is installed from the same local or +remote git repository as the parent plugin that specifies the +`<dependency>` tag. + +Note that the `subdir` always specifies a path relative to the _root_ +of the git repository, not the parent plugin. This is true even if you +installed the plugin with a local path directly to it. Plugman finds +the root of the git repository and then finds the other plugin from +there. + +## _platform_ Element + +The `<platform>` tag identifies platforms that have associated native +code or require modifications to their configuration files. Tools +using this specification can identify supported platforms and install +the code into Cordova projects. + +Plugins without `<platform>` tags are assumed to be JavaScript-only, +and therefore installable on any and all platforms. + +A sample platform tag: + + <platform name="android"> + <!-- android-specific elements --> + </platform> + <platform name="ios"> + <!-- ios-specific elements --> + </platform> + +The required `name` attribute identifies a platform as supported, +associating the element's children with that platform. + +Platform names should be lowercase. Platform names, as arbitrarily +chosen, are listed: + +* amazon-fireos +* android +* blackberry10 +* ios +* wp8 +* windows8 + +## _source-file_ Element + +The `<source-file>` element identifies executable source code that +should be installed into a project. Examples: + + <!-- android --> + <source-file src="src/android/Foo.java" + target-dir="src/com/alunny/foo" /> + <!-- ios --> + <source-file src="src/ios/CDVFoo.m" /> + <source-file src="src/ios/someLib.a" framework="true" /> + <source-file src="src/ios/someLib.a" compiler-flags="-fno-objc-arc" /> + +It supports the following attributes: + +* `src` (required): + Location of the file relative to `plugin.xml`. If the `src` file + can't be found, plugman stops and reverses the installation, issues + a notification about the problem, and exits with a non-zero code. + +* `target-dir`: + A directory into which the files should be copied, relative to the + root of the Cordova project. In practice, this is most important + for Java-based platforms, where a file in the `com.alunny.foo` + package must be located within the `com/alunny/foo` directory. For + platforms where the source directory is not important, this + attribute should be omitted. + + As with assets, if the `target` of a `source-file` would overwrite + an existing file, plugman stops and reverses the installation, + issues a notification about the problem, and exits with a non-zero + code. + +* `framework` (iOS only): + If set to `true`, also adds the specified file as a framework to the + project. + +* `compiler-flags` (iOS only): + If set, assigns the specified compiler flags for the particular + source file. + +## _config-file_ Element + +Identifies an XML-based configuration file to be modified, where in +that document the modification should take place, and what should be +modified. + +Two file types that have been tested for modification with this +element are `xml` and `plist` files. + +The `config-file` element only allows you to append new children to an +XML document tree. The children are XML literals to be inserted in the +target document. + +Example for XML: + + <config-file target="AndroidManifest.xml" parent="/manifest/application"> + <activity android:name="com.foo.Foo" android:label="@string/app_name"> + <intent-filter> + </intent-filter> + </activity> + </config-file> + +Example for `plist`: + + <config-file target="*-Info.plist" parent="CFBundleURLTypes"> + <array> + <dict> + <key>PackageName</key> + <string>$PACKAGE_NAME</string> + </dict> + </array> + </config-file> + +It supports the following attributes: + +* `target`: + + The file to be modified, and the path relative to the root of the + Cordova project. + + The target can include wildcard (`*`) elements. In this case, + plugman recursively searches through the project directory structure + and uses the first match. + + On iOS, the location of configuration files relative to the project + directory root is not known, so specifying a target of `config.xml` + resolves to `cordova-ios-project/MyAppName/config.xml`. + + If the specified file does not exist, the tool ignores the + configuration change and continues installation. + +* `parent`: An XPath selector referencing the parent of the elements + to be added to the config file. If you use absolute selectors, you + can use a wildcard (`*`) to specify the root element, + e.g., `/*/plugins`. + + For `plist` files, the `parent` determines under what parent key the + specified XML should be inserted. + + If the selector does not resolve to a child of the specified + document, the tool stops and reverses the installation process, + issues a warning, and exits with a non-zero code. + +* `after`: A prioritized list of accepted siblings after which to add the XML snippet. Useful for specifying changes in files which require strict ordering of XML elements like [http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement](http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff769509%28v=vs.105%29.aspx#BKMK_EXTENSIONSelement) + +The Windows platform supports two additional attributes (both optional) when affecting the meta-name `package.appxmanifest`: + +The `device-target` attribute indicates that the should only be included when building for the specified target device +type. Supported values are `win`, `phone`, or `all`. + +The `versions` attribute indicates that app manifests for specific Windows versions should only be altered for versions that match the +specified version string. Value can be any valid node semantic version range string. + +Examples of using these Windows specific attributes: + + <config-file target="package.appxmanifest" parent="/Package/Capabilities" versions="<8.1.0"> + <Capability Name="picturesLibrary" /> + <DeviceCapability Name="webcam" /> + </config-file> + <config-file target="package.appxmanifest" parent="/Package/Capabilities" versions=">=8.1.0" device-target="phone"> + <DeviceCapability Name="webcam" /> + </config-file> + +The above example will set pre-8.1 platforms (Windows 8, specifically) to require the `webcam` device capability and the `picturesLibrary` general capability, and apply the `webcam` device capability only to Windows 8.1 projects that build for Windows Phone. Windows desktop 8.1 systems are unmodified. + +## _plugins-plist_ Element + +This is _outdated_ as it only applies to cordova-ios 2.2.0 and +below. Use the `<config-file>` tag for newer versions of Cordova. + +Example: + + <config-file target="config.xml" parent="/widget/plugins"> + <feature name="ChildBrowser"> + <param name="ios-package" value="ChildBrowserCommand"/> + </feature> + </config-file> + +Specifies a key and value to append to the correct `AppInfo.plist` +file in an iOS Cordova project. For example: + + <plugins-plist key="Foo" string="CDVFoo" /> + +## _resource-file_ and _header-file_ Elements + +Like source files, but specifically for platforms such as iOS that +distinguish between source files, headers, and resources. iOS Examples: + + <resource-file src="CDVFoo.bundle" /> + <resource-file src="CDVFooViewController.xib" /> + <header-file src="CDVFoo.h" /> + +Android example: + + <resource-file src="FooPluginStrings.xml" target="res/values/FooPluginStrings.xml" /> + +The Windows platform supports `resource-file` only and three additional attributes +(all optional) to refine when the resource-file should be included: + +* `arch`: Indicates that the file should only be included when building for the specified architecture. + Supported values are `x86`, `x64` or `ARM`. + +* `device-target`: Indicates that the file should only be included when building for the specified target device + type. Supported values are `win` (or `windows`), `phone` or `all`. + +* `versions`: Indicates that the file should only be included when building for versions that match the specified version + string. Value can be any valid node semantic version range string. + +Windows example: + + <resource-file src="src/windows/win81/MobServices.pri" target="win81/MobServices.pri" + device-target="windows" versions="8.1" arch="x64"/> + +## _lib-file_ Element + +Like source, resource, and header files, but specifically for +platforms such as BlackBerry 10 that use user-generated libraries. +Examples: + + <lib-file src="src/BlackBerry10/native/device/libfoo.so" arch="device" /> + <lib-file src="src/BlackBerry10/native/simulator/libfoo.so" arch="simulator" /> + +Supported attributes: + +* `src` (required): + The location of the file relative to `plugin.xml`. + If `src` can't be found, plugman stops and reverses the + installation, issues a warning about the problem, and exits with a + non-zero code. + +* `arch`: The architecture for which the `.so` file has been built, + either `device` or `simulator`. + +For the Windows platform, the `<lib-file>` element allows the inclusion of an `<SDKReference>` in the generated Windows +project files. + +Supported attributes: + +* `src` (required): + The name of the SDK to include (which will be used as value of the `Include` attribute of the generated + `<SDKReference>` element). + +* `arch`: Indicates that the `<SDKReference>` should only be included when building for the specified architecture. + Supported values are `x86`, `x64` or `ARM`. + +* `device-target`: Indicates that the `<SDKReference>` should only be included when building for the specified target device + type. Supported values are `win` (or `windows`), `phone` or `all`. + +* `versions`: Indicates that the `<SDKReference>` should only be included when building for versions that match the specified version + string. Value can be any valid node semantic version range string. + +Examples: + + <lib-file src="Microsoft.WinJS.2.0, Version=1.0" arch="x86" /> + <lib-file src="Microsoft.WinJS.2.0, Version=1.0" versions=">=8.1" /> + <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="phone" /> + <lib-file src="Microsoft.WinJS.2.0, Version=1.0" target="win" versions="8.0" arch="x86" /> + +## _framework_ Element + +Identifies a framework (usually part of the OS/platform) on which the plugin depends. + +The optional `custom` attribute is a boolean indicating whether the framework is one that is included as part of your +plugin files (thus it is not a system framework). + +### _framework_ for iOS + + <framework src="libsqlite3.dylib" /> + <framework src="social.framework" weak="true" /> + <framework src="relative/path/to/my.framework" custom="true" /> + +The optional `weak` attribute is a boolean indicating whether the +framework should be weakly linked. The default is `false`. + +### _framework_ for Android + +On Android (as of [email protected]), _framework_ tags are used to include Maven dependencies, or to include bundled library projects. + +Examples: + + <!-- Depend on latest version of GCM from play services --> + <framework src="com.google.android.gms:play-services-gcm:+" /> + <!-- Depend on v21 of appcompat-v7 support library --> + <framework src="com.android.support:appcompat-v7:21+" /> + <!-- Depend on library project included in plugin --> + <framework src="relative/path/FeedbackLib" custom="true" /> + +_framework_ can also be used to have custom .gradle files sub-included into the main project's .gradle file: + + <framework src="relative/path/rules.gradle" custom="true" type="gradleReference" /> + +For [email protected] (ANT-based projects): + +The optional `type` attribute is a string indicating the type of framework to add. Currently only `projectReference` is +supported and only for Windows. Using `custom='true'` and `type='projectReference'` will add a reference to the project +which will be added to the compile+link steps of the cordova project. This essentially is the only way currently that a +'custom' framework can target multiple architectures as they are explicitly built as a dependency by the referencing +cordova application. + +The optional `parent` sets the relative path to the directory containing the +sub-project to which to add the reference. The default is `.`, i.e. the +application project. It allows to add references between sub projects like in this example: + + <framework src="extras/android/support/v7/appcompat" custom="false" parent="FeedbackLib" /> + +### _framework_ for Windows + +The Windows platform supports four additional attributes (all optional) to refine when the framework should be included and to adjust target location: + + <framework src="path/to/project/LibProj.csproj" custom="true" type="projectReference"/> + +The `arch` attribute indicates that the framework should only be included when building for the specified architecture. +Supported values are `x86`, `x64` or `ARM`. + +The `device-target` attribute indicates that the framework should only be included when building for the specified target device +type. Supported values are `win` (or `windows`), `phone` or `all`. + +The `versions` attribute indicates that the framework should only be included when building for versions that match the +specified version string. Value can be any valid node semantic version range string. + +The `target-dir` attribute indicates a subdirectory into which the framework should be +copied. In practice, this is most important when plugin contains different framework +versions for different chip architectures or device targets, but which have the same name. This allows you to specify different subfolders for each framework version so that they +don't overlap each other. + +Examples of using these Windows specific attributes: + + <framework src="src/windows/example.dll" arch="x64" /> + <framework src="src/windows/example.dll" versions=">=8.0" /> + <framework src="src/windows/example.vcxproj" type="projectReference" target="win" /> + <framework src="src/windows/example.vcxproj" type="projectReference" target="all" versions="8.1" arch="x86" /> + <framework src="src/windows/example.dll" target-dir="bin/x64" arch="x64" custom="true"/> + +## _info_ Element + +Additional information provided to users. This is useful when you +require extra steps that can't be easily automated or are beyond +plugman's scope. Examples: + + <info> + You need to install __Google Play Services__ from the `Android Extras` section using the Android SDK manager (run `android`). + + You need to add the following line to the `local.properties`: + + android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib + </info> + +## _hook_ Element + +Represents your custom script which will be called by Cordova when +certain action occurs (for example, after plugin is added or platform +prepare logic is invoked). This is useful when you need to extend +default Cordova functionality. See [Hooks Guide](../guide/appdev/hooks/index.html) for more information. + + <hook type="after_plugin_install" src="scripts/afterPluginInstall.js" /> + +## Variables + +In certain cases, a plugin may need to make configuration changes +dependent on the target application. For example, to register for C2DM +on Android, an app whose package id is `com.alunny.message` would +require a permission such as: + + <uses-permission android:name="com.alunny.message.permission.C2D_MESSAGE"/> + +In such cases where the content inserted from the `plugin.xml` file is +not known ahead of time, variables can be indicated by a dollar-sign +followed by a series of capital letters, digits, or underscores. For +the above example, the `plugin.xml` file would include this tag: + + <uses-permission android:name="$PACKAGE_NAME.permission.C2D_MESSAGE"/> + +plugman replaces variable references with the specified value, or the +empty string if not found. The value of the variable reference may be +detected (in this case, from the `AndroidManifest.xml` file) or +specified by the user of the tool; the exact process is dependent on +the particular tool. + +plugman can request users to specify a plugin's required +variables. For example, API keys for C2M and Google Maps can be +specified as a command-line argument: + + plugman --platform android --project /path/to/project --plugin name|git-url|path --variable API_KEY=!@CFATGWE%^WGSFDGSDFW$%^#$%YTHGsdfhsfhyer56734 + +To make the variable mandatory, the `<platform>` tag needs to contain +a `<preference>` tag. For example: + + <preference name="API_KEY" default="default-value" /> + +plugman checks that these required preferences are passed in. If not, +it should warn the user how to pass the variable in and exit with a +non-zero code. If the optional `default` attribute is present its value will be used and no error will be emitted. + +Certain variable names should be reserved, as listed below. + +## $PACKAGE_NAME + +The reverse-domain style unique identifier for the package, +corresponding to the `CFBundleIdentifier` on iOS or the `package` +attribute of the top-level `manifest` element in an +`AndroidManifest.xml` file. http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/config.json ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/config.json b/www/docs/en/edge/config.json deleted file mode 100644 index 99f6553..0000000 --- a/www/docs/en/edge/config.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "language": "English", - "merge": { - "events.md": [ - "cordova/events/events.md", - "cordova/events/events.deviceready.md", - "cordova/events/events.pause.md", - "cordova/events/events.resume.md", - "cordova/events/events.backbutton.md", - "cordova/events/events.menubutton.md", - "cordova/events/events.searchbutton.md", - "cordova/events/events.startcallbutton.md", - "cordova/events/events.endcallbutton.md", - "cordova/events/events.volumedownbutton.md", - "cordova/events/events.volumeupbutton.md" - ] - } -} http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f061b980/www/docs/en/edge/config_ref/images.md ---------------------------------------------------------------------- diff --git a/www/docs/en/edge/config_ref/images.md b/www/docs/en/edge/config_ref/images.md deleted file mode 100644 index 5d81eca..0000000 --- a/www/docs/en/edge/config_ref/images.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -license: > - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - -title: Icons and Splash Screens ---- - -# Icons and Splash Screens - -This section shows how to configure an app's icon and optional splash -screen for various platforms, both when working in the Cordova CLI -(described in The Command-Line Interface) or using platform-specific -SDK tools (detailed in the Platform Guides). - -## Configuring Icons in the CLI - -When working in the CLI you can define app icon(s) via `<icon>` element (`config.xml`). -If you do not specify an icon then the Apache Cordova logo is used. - - <icon src="res/ios/icon.png" platform="ios" width="57" height="57" density="mdpi" /> - -src: (required) specifies the location of the image file, relative to your project directory - -platform: (optional) target platform - -width: (optional) icon width in pixels - -height: (optional) icon height in pixels - -density: (optional) android specific, specifies icon density - -The following configuration can be used to define single default icon -which will be used for all platforms. - - <icon src="res/icon.png" /> - -For each platform you can also define a pixel-perfect icons set to fit -different screen resolutions. - -Amazon Fire OS - - <platform name="amazon-fireos"> - <icon src="res/android/ldpi.png" density="ldpi" /> - <icon src="res/android/mdpi.png" density="mdpi" /> - <icon src="res/android/hdpi.png" density="hdpi" /> - <icon src="res/android/xhdpi.png" density="xhdpi" /> - </platform> - -Android - - <platform name="android"> - <icon src="res/android/ldpi.png" density="ldpi" /> - <icon src="res/android/mdpi.png" density="mdpi" /> - <icon src="res/android/hdpi.png" density="hdpi" /> - <icon src="res/android/xhdpi.png" density="xhdpi" /> - </platform> - -BlackBerry10 - - <platform name="blackberry10"> - <icon src="res/bb10/icon-86.png" /> - <icon src="res/bb10/icon-150.png" /> - </platform> - -See BlackBerry's documentation for targeting multiple sizes and locales. -[http://developer.blackberry.com/html5/documentation/icon_element.html] - -Firefox OS - - <platform name="firefoxos"> - <icon src="res/ff/logo.png" width="60" height="60" /> - </platform> - -iOS - - <platform name="ios"> - <!-- iOS 8.0+ --> - <!-- iPhone 6 Plus --> - <icon src="res/ios/[email protected]" width="180" height="180" /> - <!-- iOS 7.0+ --> - <!-- iPhone / iPod Touch --> - <icon src="res/ios/icon-60.png" width="60" height="60" /> - <icon src="res/ios/[email protected]" width="120" height="120" /> - <!-- iPad --> - <icon src="res/ios/icon-76.png" width="76" height="76" /> - <icon src="res/ios/[email protected]" width="152" height="152" /> - <!-- iOS 6.1 --> - <!-- Spotlight Icon --> - <icon src="res/ios/icon-40.png" width="40" height="40" /> - <icon src="res/ios/[email protected]" width="80" height="80" /> - <!-- iPhone / iPod Touch --> - <icon src="res/ios/icon.png" width="57" height="57" /> - <icon src="res/ios/[email protected]" width="114" height="114" /> - <!-- iPad --> - <icon src="res/ios/icon-72.png" width="72" height="72" /> - <icon src="res/ios/[email protected]" width="144" height="144" /> - <!-- iPhone Spotlight and Settings Icon --> - <icon src="res/ios/icon-small.png" width="29" height="29" /> - <icon src="res/ios/[email protected]" width="58" height="58" /> - <!-- iPad Spotlight and Settings Icon --> - <icon src="res/ios/icon-50.png" width="50" height="50" /> - <icon src="res/ios/[email protected]" width="100" height="100" /> - </platform> - -Windows Phone8 - - <platform name="wp8"> - <icon src="res/wp/ApplicationIcon.png" width="99" height="99" /> - <!-- tile image --> - <icon src="res/wp/Background.png" width="159" height="159" /> - </platform> - -Windows8 - - <platform name="windows8"> - <icon src="res/windows8/logo.png" width="150" height="150" /> - <icon src="res/windows8/smalllogo.png" width="30" height="30" /> - <icon src="res/windows8/storelogo.png" width="50" height="50" /> - </platform> - -## Configuring Splash Screens in the CLI - -In the top-level `config.xml` file (not the one in `platforms`), add configuration elements like those specified here. - -# Example configuration - -Please notice that the value of the "src" attribute is relative to the project directory and not to the www directory. -You can name the source image whatever you like. The internal name in the app are determined by Cordova. - - <platform name="android"> - <!-- you can use any density that exists in the Android project --> - <splash src="res/screen/android/splash-land-hdpi.png" density="land-hdpi"/> - <splash src="res/screen/android/splash-land-ldpi.png" density="land-ldpi"/> - <splash src="res/screen/android/splash-land-mdpi.png" density="land-mdpi"/> - <splash src="res/screen/android/splash-land-xhdpi.png" density="land-xhdpi"/> - - <splash src="res/screen/android/splash-port-hdpi.png" density="port-hdpi"/> - <splash src="res/screen/android/splash-port-ldpi.png" density="port-ldpi"/> - <splash src="res/screen/android/splash-port-mdpi.png" density="port-mdpi"/> - <splash src="res/screen/android/splash-port-xhdpi.png" density="port-xhdpi"/> - </platform> - - <platform name="ios"> - <!-- images are determined by width and height. The following are supported --> - <splash src="res/screen/ios/Default~iphone.png" width="320" height="480"/> - <splash src="res/screen/ios/Default@2x~iphone.png" width="640" height="960"/> - <splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/> - <splash src="res/screen/ios/Default-Portrait@2x~ipad.png" width="1536" height="2048"/> - <splash src="res/screen/ios/Default-Landscape~ipad.png" width="1024" height="768"/> - <splash src="res/screen/ios/Default-Landscape@2x~ipad.png" width="2048" height="1536"/> - <splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/> - <splash src="res/screen/ios/Default-667h.png" width="750" height="1334"/> - <splash src="res/screen/ios/Default-736h.png" width="1242" height="2208"/> - <splash src="res/screen/ios/Default-Landscape-736h.png" width="2208" height="1242"/> - </platform> - - <platform name="wp8"> - <!-- images are determined by width and height. The following are supported --> - <splash src="res/screen/wp8/SplashScreenImage.jpg" width="768" height="1280"/> - </platform> - - <platform name="windows8"> - <!-- images are determined by width and height. The following are supported --> - <splash src="res/screen/windows8/splashscreen.png" width="620" height="300"/> - </platform> - - <platform name="blackberry10"> - <!-- Add a rim:splash element for each resolution and locale you wish --> - <!-- http://developer.blackberry.com/html5/documentation/rim_splash_element.html --> - <rim:splash src="res/screen/windows8/splashscreen.png"/> - </platform> - - - <preference name="SplashScreenDelay" value="10000" /> - -# Supported platforms - -As of now (Cordova 3.5.0 July 2014) the following platforms support splash screens. - - android - ios - wp8 - windows8 - blackberry10 - -# Splashscreen Plugin - - Apache Cordova also offers special splash screen plugin which could be used to programmatically display and hide a splash screen during application launch - https://github.com/apache/cordova-plugin-splashscreen - - --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
