From c3f3028f49a93f9aa8aa26043a53693d93d447a7 Mon Sep 17 00:00:00 2001 From: Richard Knoll Date: Wed, 4 May 2016 17:52:46 -0700 Subject: [PATCH 1/2] CB-11203: Improving documentation of plugin CLI variables --- www/docs/en/dev/config_ref/index.md | 18 ++++++++++++++++++ www/docs/en/dev/plugin_ref/spec.md | 12 ++++++++++-- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/www/docs/en/dev/config_ref/index.md b/www/docs/en/dev/config_ref/index.md index 7d5878d33e..625c612fb5 100644 --- a/www/docs/en/dev/config_ref/index.md +++ b/www/docs/en/dev/config_ref/index.md @@ -234,6 +234,23 @@ platform. See [Customize icons topic](images.html) for more information. ``` +### variable + Persists the value of a CLI variable to be used when restoring a plugin during a prepare. See the [preference element][plugin_preference] + of `plugin.xml` for more details. + + Attributes(type) | Description + ----------------- | ------------ + name(string) | *Required*
Name of the CLI variable. Can only contain capital letters, digits, and underscores. + value(string) | *Required*
Value of the CLI variable to be used when restoring the parent plugin during a prepare. + + Examples: + + ```xml + + + + ``` + ## 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,6 +489,7 @@ 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 [whitelist_navigation]: ../reference/cordova-plugin-whitelist/index.html#navigation-whitelist [whitelist_intent]: ../reference/cordova-plugin-whitelist/index.html#intent-whitelist diff --git a/www/docs/en/dev/plugin_ref/spec.md b/www/docs/en/dev/plugin_ref/spec.md index 2fc4b0247e..b9d0a849cf 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 `` tag needs to contain a `` 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) | Description ---------------- | ------------ -name(string) | *Required*
Name of the variable. +name(string) | *Required*
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 - + + + + + $MY_CUSTOM_STRING + ``` From a9c9e8697c47ba4e1bc4d9da6fa90fc75609b5f2 Mon Sep 17 00:00:00 2001 From: Richard Knoll Date: Mon, 9 May 2016 11:15:17 -0700 Subject: [PATCH 2/2] Adding info about --save and prepare --- www/docs/en/dev/config_ref/index.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/www/docs/en/dev/config_ref/index.md b/www/docs/en/dev/config_ref/index.md index 625c612fb5..d88d518cb8 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) | Description ----------------- | ------------ @@ -235,8 +238,16 @@ platform. See [Customize icons topic](images.html) for more information. ``` ### variable - Persists the value of a CLI variable to be used when restoring a plugin during a prepare. See the [preference element][plugin_preference] - of `plugin.xml` for more details. + 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) | Description ----------------- | ------------ @@ -491,6 +502,7 @@ platform. See [Customize icons topic](images.html) for more information. [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/