cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rkn...@apache.org
Subject docs commit: CB-11203: Improving documentation of plugin CLI variables
Date Mon, 09 May 2016 18:40:56 GMT
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 <richard.b.knoll@gmail.com>
Authored: Wed May 4 17:52:46 2016 -0700
Committer: Richard Knoll <richard.b.knoll@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


Mime
View raw message