Skip to content

CB-11203: Improving documentation of plugin CLI variables #595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

CB-11203: Improving documentation of plugin CLI variables #595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c3f3028
CB-11203: Improving documentation of plugin CLI variables
riknoll May 5, 2016
a9c9e86
Adding info about --save and prepare
riknoll May 9, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion www/docs/en/dev/config_ref/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------------- | ------------
Expand All @@ -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) | 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.
Expand Down Expand Up @@ -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/
12 changes: 10 additions & 2 deletions www/docs/en/dev/plugin_ref/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) | 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>
```