You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by rk...@apache.org on 2016/05/09 18:40:56 UTC
docs commit: CB-11203: Improving documentation of plugin CLI variables
Repository: cordova-docs
Updated Branches:
refs/heads/master fbb4213c2 -> e965e6a92
CB-11203: Improving documentation of plugin CLI variables
This closes #595
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/e965e6a9
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/e965e6a9
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/e965e6a9
Branch: refs/heads/master
Commit: e965e6a9293178b3a929f3822e7ab1aff2779e98
Parents: fbb4213
Author: Richard Knoll <ri...@gmail.com>
Authored: Wed May 4 17:52:46 2016 -0700
Committer: Richard Knoll <ri...@gmail.com>
Committed: Mon May 9 11:37:42 2016 -0700
----------------------------------------------------------------------
www/docs/en/dev/config_ref/index.md | 32 +++++++++++++++++++++++++++++++-
www/docs/en/dev/plugin_ref/spec.md | 12 ++++++++++--
2 files changed, 41 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e965e6a9/www/docs/en/dev/config_ref/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/config_ref/index.md b/www/docs/en/dev/config_ref/index.md
index 114d9fd..70ecf21 100644
--- a/www/docs/en/dev/config_ref/index.md
+++ b/www/docs/en/dev/config_ref/index.md
@@ -220,7 +220,10 @@ platform. See [Customize icons topic](images.html) for more information.
```
## plugin
- Specifies details about what plugin to restore during a prepare.
+ Specifies details about what plugin to restore during a prepare. This element
+ is automatically added to a project's `config.xml` when a plugin is added using
+ the `--save` flag. See the [CLI reference][plugin_cli] for more information on
+ adding plugins.
Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
----------------- | ------------
@@ -234,6 +237,31 @@ platform. See [Customize icons topic](images.html) for more information.
<plugin name="cordova-plugin-device" spec="https://github.com/apache/cordova-plugin-device.git#1.0.0" />
```
+### variable
+ Persists the value of a CLI variable to be used when restoring a plugin during a
+ prepare. This element is added to `config.xml` when a plugin that uses CLI variables
+ is added using the `--save` flag. See the [CLI reference][plugin_cli] for more
+ information on adding plugins.
+
+ Note that this value is only used when the plugin is restored to the project during a
+ prepare, changing it will *not* change the value used by the plugin in the current
+ project. In order for changes to this value to take effect, remove the plugin from the
+ project and restore it by running `cordova prepare`. See the
+ [preference element][plugin_preference] of `plugin.xml` for more details on CLI variables.
+
+ Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
+ ----------------- | ------------
+ name(string) | *Required* <br/> Name of the CLI variable. Can only contain capital letters, digits, and underscores.
+ value(string) | *Required* <br/> Value of the CLI variable to be used when restoring the parent plugin during a prepare.
+
+ Examples:
+
+ ```xml
+ <plugin name="cordova-plugin-device" spec="^1.1.0">
+ <variable name="MY_VARIABLE" value="my_variable_value" />
+ </plugin>
+ ```
+
## preference
Sets various options as pairs of name/value attributes. Each preference's name is case-insensitive. Many preferences are unique to specific platforms,
and will be indicated as such.
@@ -472,7 +500,9 @@ platform. See [Customize icons topic](images.html) for more information.
[uses-sdk]: http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
[platform_spec]: ../reference/cordova-cli/index.html#platform-spec
+[plugin_preference]: ../plugin_ref/spec.html#preference
[plugin_spec]: ../reference/cordova-cli/index.html#plugin-spec
+[plugin_cli]: ../reference/cordova-cli/index.html#cordova-plugin-command
[whitelist_navigation]: ../reference/cordova-plugin-whitelist/index.html#navigation-whitelist
[whitelist_intent]: ../reference/cordova-plugin-whitelist/index.html#intent-whitelist
[statusbar_plugin]: ../reference/cordova-plugin-statusbar/
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/e965e6a9/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
index d798254..c70d48f 100644
--- a/www/docs/en/dev/plugin_ref/spec.md
+++ b/www/docs/en/dev/plugin_ref/spec.md
@@ -506,13 +506,21 @@ Certain variable names should be reserved, like `$PACKAGE_NAME`. This is the rev
As seen in the previous section, sometimes plugin might require user to specify values for their variables. To make those variable mandatory, the `<platform>` tag needs to contain
a `<preference>` tag.
The CLI 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.
+Preferences can be referenced elsewhere in `plugin.xml` using the syntax `$PREFERENCE_NAME`.
Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Description
---------------- | ------------
-name(string) | *Required* <br/> Name of the variable.
+name(string) | *Required* <br/> Name of the variable. Can only contain capital letters, digits, and underscores.
default(string) | Default value of the variable. If present, its value will be used and no error will be emitted in case user does not enter any value.
Example:
```xml
-<preference name="API_KEY" default="default-value" />
+<preference name="MY_CUSTOM_STRING" default="default-value" />
+
+<!--
+ The preference may be referenced elsewhere in plugin.xml like so:
+-->
+<config-file target="./res/values/strings.xml" parent="/resources">
+ <string name="custom">$MY_CUSTOM_STRING</string>
+</config-file>
```
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org