Updated Branches: refs/heads/master a85a9d6fb -> 9982d9a01
[CB-3827] move plugin spec & plugman doc to new top-level plugin_ref dir Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/1012ba0a Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/1012ba0a Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/1012ba0a Branch: refs/heads/master Commit: 1012ba0a0cfb3781820af3bea2bc01cccfc4f18a Parents: a85a9d6 Author: Mike Sierra <[email protected]> Authored: Thu Jul 18 16:22:37 2013 -0400 Committer: Michael Brooks <[email protected]> Committed: Thu Jul 18 14:00:16 2013 -0700 ---------------------------------------------------------------------- docs/en/edge/guide/plugins/corePluginInstall.md | 110 ---- docs/en/edge/guide/plugins/plugin_spec.md | 502 ------------------- docs/en/edge/plugin_ref/plugman.md | 110 ++++ docs/en/edge/plugin_ref/spec.md | 502 +++++++++++++++++++ 4 files changed, 612 insertions(+), 612 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1012ba0a/docs/en/edge/guide/plugins/corePluginInstall.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/plugins/corePluginInstall.md b/docs/en/edge/guide/plugins/corePluginInstall.md deleted file mode 100644 index 7b8f01e..0000000 --- a/docs/en/edge/guide/plugins/corePluginInstall.md +++ /dev/null @@ -1,110 +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. ---- - -# 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. The first is by using the -`cordova` CLI described in The Command-line Interface. The second is -by using a lower-level -[plugman](https://github.com/apache/cordova-plugman/) -command-line interface. This guide concentrates on the second -approach, which may be useful for developers who want to upgrade their -version of Cordova, but who haven't yet adopted the Cordova CLI in -their workflow. - -For more information on plugman, see -[the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md). - -## Basic Commands - -To install plugman, you must have [node](http://nodejs.org/) installed -on your machine: - - npm install -g plugman - -Here is the syntax to add a plugin for each platform: - - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]] - -To uninstall a plugin: - - plugman --uninstall --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>] - -## 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|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status.git - -* cordova-plugin-camera - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git - -* cordova-plugin-console - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.git - -* cordova-plugin-contacts - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts.git - -* cordova-plugin-device - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git - -* cordova-plugin-device-motion (accelerometer) - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-motion.git - -* cordova-plugin-device-orientation (compass) - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation.git - -* cordova-plugin-dialogs - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git - -* cordova-plugin-file - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-file.git - -* cordova-plugin-file-transfer - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer.git - -* cordova-plugin-geolocation - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git - -* cordova-plugin-globalization - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization.git - -* cordova-plugin-inappbrowser - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git - -* cordova-plugin-media - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-media.git - -* cordova-plugin-media-capture - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-media-capture.git - -* cordova-plugin-network-information - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git - -* cordova-plugin-splashscreen - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-splashscreen.git - -* cordova-plugin-vibration - plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1012ba0a/docs/en/edge/guide/plugins/plugin_spec.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/guide/plugins/plugin_spec.md b/docs/en/edge/guide/plugins/plugin_spec.md deleted file mode 100644 index 63b9b0c..0000000 --- a/docs/en/edge/guide/plugins/plugin_spec.md +++ /dev/null @@ -1,502 +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. ---- - -# 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" /> - </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> - -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. - -## <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 acccessed 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> - -The `<dependency>` tag allows you 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> - -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: - -* android -* bb10 -* ios -* wp7 -* wp8 - -## <source-file> - -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 - cannot 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> - -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. - -## <plugins-plist> - -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"> - <plugin name="ChildBrowser" value="ChildBrowserCommand"/> - </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> - -Like source files, but specifically for platforms such as iOS that -distinguish between source files, headers, and resources. Examples: - - <resource-file src="CDVFoo.bundle" /> - <resource-file src="CDVFooViewController.xib" /> - <header-file src="CDVFoo.h" /> - -## <lib-file> - -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` cannot 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`. - -## <framework> - -Identifies a framework (usually part of the OS/platform) on which the plugin depends. - -Examples: - - <framework src="libsqlite3.dylib" /> - <framework src="social.framework" weak="true" /> - - - - -The `src` attribute identifies the framework, which plugman attempts -to add to the Cordova project, in the correct fashion for a given -platform. - -The optional `weak` attribute is a boolean indicating whether the -framework should be weakly linked. The default is `false`. - -## <info> - -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 your `local.properties` - - android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib - </info> - -# 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" /> - -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. - -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/1012ba0a/docs/en/edge/plugin_ref/plugman.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/plugin_ref/plugman.md b/docs/en/edge/plugin_ref/plugman.md new file mode 100644 index 0000000..7b8f01e --- /dev/null +++ b/docs/en/edge/plugin_ref/plugman.md @@ -0,0 +1,110 @@ +--- +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. +--- + +# 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. The first is by using the +`cordova` CLI described in The Command-line Interface. The second is +by using a lower-level +[plugman](https://github.com/apache/cordova-plugman/) +command-line interface. This guide concentrates on the second +approach, which may be useful for developers who want to upgrade their +version of Cordova, but who haven't yet adopted the Cordova CLI in +their workflow. + +For more information on plugman, see +[the README file in its repository](https://github.com/apache/cordova-plugman/blob/master/README.md). + +## Basic Commands + +To install plugman, you must have [node](http://nodejs.org/) installed +on your machine: + + npm install -g plugman + +Here is the syntax to add a plugin for each platform: + + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]] + +To uninstall a plugin: + + plugman --uninstall --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>] + +## 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|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status.git + +* cordova-plugin-camera + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git + +* cordova-plugin-console + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.git + +* cordova-plugin-contacts + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts.git + +* cordova-plugin-device + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git + +* cordova-plugin-device-motion (accelerometer) + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-motion.git + +* cordova-plugin-device-orientation (compass) + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation.git + +* cordova-plugin-dialogs + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git + +* cordova-plugin-file + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-file.git + +* cordova-plugin-file-transfer + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer.git + +* cordova-plugin-geolocation + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git + +* cordova-plugin-globalization + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization.git + +* cordova-plugin-inappbrowser + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git + +* cordova-plugin-media + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-media.git + +* cordova-plugin-media-capture + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-media-capture.git + +* cordova-plugin-network-information + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git + +* cordova-plugin-splashscreen + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-splashscreen.git + +* cordova-plugin-vibration + plugman --platform <ios|android|blackberry10|wp7|wp8> --project <directory> --plugin https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/1012ba0a/docs/en/edge/plugin_ref/spec.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/plugin_ref/spec.md b/docs/en/edge/plugin_ref/spec.md new file mode 100644 index 0000000..63b9b0c --- /dev/null +++ b/docs/en/edge/plugin_ref/spec.md @@ -0,0 +1,502 @@ +--- +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. +--- + +# 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" /> + </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> + +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. + +## <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 acccessed 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> + +The `<dependency>` tag allows you 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> + +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: + +* android +* bb10 +* ios +* wp7 +* wp8 + +## <source-file> + +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 + cannot 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> + +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. + +## <plugins-plist> + +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"> + <plugin name="ChildBrowser" value="ChildBrowserCommand"/> + </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> + +Like source files, but specifically for platforms such as iOS that +distinguish between source files, headers, and resources. Examples: + + <resource-file src="CDVFoo.bundle" /> + <resource-file src="CDVFooViewController.xib" /> + <header-file src="CDVFoo.h" /> + +## <lib-file> + +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` cannot 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`. + +## <framework> + +Identifies a framework (usually part of the OS/platform) on which the plugin depends. + +Examples: + + <framework src="libsqlite3.dylib" /> + <framework src="social.framework" weak="true" /> + + + + +The `src` attribute identifies the framework, which plugman attempts +to add to the Cordova project, in the correct fashion for a given +platform. + +The optional `weak` attribute is a boolean indicating whether the +framework should be weakly linked. The default is `false`. + +## <info> + +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 your `local.properties` + + android.library.reference.1=PATH_TO_ANDROID_SDK/sdk/extras/google/google_play_services/libproject/google-play-services_lib + </info> + +# 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" /> + +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. + +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.
