cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Horn, Julian C" <>
Subject RE: Questions re: plugin variables
Date Fri, 07 Nov 2014 15:18:54 GMT
Leo's question really hasn't been answered yet.  Let me try to make this more concrete and
see if anyone can explain whether the current behavior of the CLI is correct or not.

The plugin.xml in the StatusBar plugin contains the following content:

<platform name="ios">
    <config-file target="config.xml" parent="/*">.
          <preference name="StatusBarOverlaysWebView" value="true" />

There are several mysteries here.

1) What does it mean if the name attribute of a preference tag does not obey the "only capital
letters, digits, or underscores" rule?  Apparently it can never cause variable replacement.
2) What does the value attribute mean?  Does this supply a default value for a variable if
the variable is not mentioned in the --variable flag (thus making the variable "optional")?
3) Where can <preference> tags legally appear?  Must they be outside of <platform>
tags, or can they be inside <platform> tags or even inside <config-file> tags?

Our experiments with CLI 4.0.1-dev show the following:

1) The value attribute is ignored by the CLI, or at least it doesn't create a default value.

For example, suppose you put the following preference tag outside of any <platform>
<preference name="API_KEY" value="my-api-key" />
We found that the user is still required to supply --variable API_KEY, which means that "my-api-key"
never becomes the value of API_KEY.

2) <preference> tags appear to be ignored by the CLI if they appear below a <platform>

If you move the <preference> node shown above from outside a <platform> node to
inside a <platform> node, then the CLI stops prompting for a --variable flag and $API_KEY
is not replaced by anything.

It looks to us like the <preference> tag is overloaded.  When it appears outside the
<platform> tag it defines a variable.  When it appears inside a <platform> tag
it does not.  The meaning of the <preference> tag within a <platform> tag is apparently
determined by the platform.

If people agree that this is correct then the documentation can be updated accordingly.  However,
we did see some code in the implementation that seemed to be looking for <preference>
tags inside of <platform> tags.  It seems like this isn't working as intended, but then
again we can't figure out what the intention is.


-----Original Message-----
From: Marcel Kinard [] 
Sent: Friday, November 07, 2014 9:42 AM
Subject: Re: Questions re: plugin variables

If there is a reasonable question from a user, it should probably be added to the docs (assuming
it's not already there).

Leo, would you like to do a pull request?

On Nov 5, 2014, at 8:24 PM, Mark Koudritsky <> wrote:

> Variables should to be provided when adding the plugin
> E.g:
>    cordova plugin add org.some.plugin --variable API_KEY=some_value
> Example of a plugin that uses variables:
> ct
> Relevant places in the code in cordova-lib:
>   Where variables are checked during plugin add:
> ova/plugin.js#L126
> man/install.js#L296
> Here each variable is replaced with its value when generating the 
> "config munge" which is an object that describes changes that need to 
> be applied to the platform dir.
> man/util/config-changes.js#L368
> On Wed, Nov 5, 2014 at 5:28 PM, Treggiari, Leo 
> <>
> wrote:
>> I'm having a hard time understanding exactly how plugin variables work.
>> It's probably a level of detail that only plugin developers and tool 
>> developers need to be concerned about.  I'd appreciate it if someone 
>> can give me the answers.
>> 1.  "variables can be indicated by a dollar-sign followed by a series 
>> of capital letters, digits, or underscores."
>>     "To make the variable mandatory, the <platform> tag needs to 
>> contain a <preference> tag."
>>     Does this mean that there are optional and required variables - i.e?
>>      -  A variable reference is defined by a lexical element which 
>> begins with a $ and is followed only by capital letters, digits, or underscores?
>>      -  A variable is made mandatory by the presence of a 
>> <preference> tag which uses the same name with the $ removed?
>>      -  Can this <preference> tag be anywhere in the plugin.xml file, 
>> or must it be the direct child of the <plugin> element or
>>         a <platform> element?
>>      -  Can the variable references be anywhere or only within strings?
>> 2.  Where and when are the variables replaced by their value?
>>      -  plugin.xml is the only place that the variable value is used 
>> and only for replacing the variable references?
>>      -  When in Cordova CLI do the values get applied - during "add", 
>> during "prepare"?
>> 3.   What happens if you combine dependencies with variables.  For
>> example, suppose A depends on B, and B requires a variable X.  How do 
>> you supply the value?
>> Thanks,
>> Leo

To unsubscribe, e-mail:
For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message