You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by "Treggiari, Leo" <le...@intel.com> on 2014/11/05 23:28:17 UTC
Questions re: plugin variables
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
RE: Questions re: plugin variables
Posted by "Horn, Julian C" <ju...@intel.com>.
Thanks, that clears everything up.
It seems the fact that <preference> tags don't work inside <platform> tags is a bug.
Fortunately there is no advantage to putting a <preference> tag inside and everyone seems to put them outside.
Julian
-----Original Message-----
From: Shazron [mailto:shazron@gmail.com]
Sent: Wednesday, November 12, 2014 6:38 PM
To: dev@cordova.apache.org
Subject: Re: Questions re: plugin variables
I know it seems confusing, but the <preference> tag inside the <config-file> tag is just some xml insertion into the config.xml file that is specified, but is not related to the <preference> tag specified for plugin.xml. It is the <preference> tag for config.xml.
It should behave as specified in the Plugin Spec [1], when inside <platform> tags, except for what I explained above.
Answering your points:
1) Yes, it ignores the value attribute, only 'name' is applicable per the spec.
2) They shouldn't be ignored if inside the <platform> node, seems to be a bug (unless the tool is smart enough to know if the variable is actually being used and not prompt -- but that seems to be bad design)
[1]
http://cordova.apache.org/docs/en/4.0.0/plugin_ref_spec.md.html#Plugin%20Specification
On Fri, Nov 7, 2014 at 7:18 AM, Horn, Julian C <ju...@intel.com>
wrote:
> 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> tag.
> <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> node.
>
> 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.
>
> Julian
>
> -----Original Message-----
> From: Marcel Kinard [mailto:cmarcelk@gmail.com]
> Sent: Friday, November 07, 2014 9:42 AM
> To: dev@cordova.apache.org
> 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 <ka...@google.com> 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:
> > http://plugins.cordova.io/#/package/com.phonegap.plugins.facebookcon
> > ne
> > ct
> >
> > Relevant places in the code in cordova-lib:
> > Where variables are checked during plugin add:
> >
> > https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/co
> > rd
> > ova/plugin.js#L126
> >
> > https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/pl
> > ug
> > 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.
> >
> > https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/pl
> > ug
> > man/util/config-changes.js#L368
> >
> >
> > On Wed, Nov 5, 2014 at 5:28 PM, Treggiari, Leo
> > <le...@intel.com>
> > 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: dev-unsubscribe@cordova.apache.org
> For additional commands, e-mail: dev-help@cordova.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
> For additional commands, e-mail: dev-help@cordova.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
Re: Questions re: plugin variables
Posted by Shazron <sh...@gmail.com>.
I know it seems confusing, but the <preference> tag inside the
<config-file> tag is just some xml insertion into the config.xml file that
is specified, but is not related to the <preference> tag specified for
plugin.xml. It is the <preference> tag for config.xml.
It should behave as specified in the Plugin Spec [1], when inside
<platform> tags, except for what I explained above.
Answering your points:
1) Yes, it ignores the value attribute, only 'name' is applicable per the
spec.
2) They shouldn't be ignored if inside the <platform> node, seems to be a
bug (unless the tool is smart enough to know if the variable is actually
being used and not prompt -- but that seems to be bad design)
[1]
http://cordova.apache.org/docs/en/4.0.0/plugin_ref_spec.md.html#Plugin%20Specification
On Fri, Nov 7, 2014 at 7:18 AM, Horn, Julian C <ju...@intel.com>
wrote:
> 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> tag.
> <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> node.
>
> 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.
>
> Julian
>
> -----Original Message-----
> From: Marcel Kinard [mailto:cmarcelk@gmail.com]
> Sent: Friday, November 07, 2014 9:42 AM
> To: dev@cordova.apache.org
> 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 <ka...@google.com> 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:
> > http://plugins.cordova.io/#/package/com.phonegap.plugins.facebookconne
> > ct
> >
> > Relevant places in the code in cordova-lib:
> > Where variables are checked during plugin add:
> >
> > https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cord
> > ova/plugin.js#L126
> >
> > https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plug
> > 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.
> >
> > https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plug
> > man/util/config-changes.js#L368
> >
> >
> > On Wed, Nov 5, 2014 at 5:28 PM, Treggiari, Leo
> > <le...@intel.com>
> > 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: dev-unsubscribe@cordova.apache.org
> For additional commands, e-mail: dev-help@cordova.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
> For additional commands, e-mail: dev-help@cordova.apache.org
>
>
RE: Questions re: plugin variables
Posted by "Horn, Julian C" <ju...@intel.com>.
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> tag.
<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> node.
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.
Julian
-----Original Message-----
From: Marcel Kinard [mailto:cmarcelk@gmail.com]
Sent: Friday, November 07, 2014 9:42 AM
To: dev@cordova.apache.org
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 <ka...@google.com> 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:
> http://plugins.cordova.io/#/package/com.phonegap.plugins.facebookconne
> ct
>
> Relevant places in the code in cordova-lib:
> Where variables are checked during plugin add:
>
> https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cord
> ova/plugin.js#L126
>
> https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plug
> 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.
>
> https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plug
> man/util/config-changes.js#L368
>
>
> On Wed, Nov 5, 2014 at 5:28 PM, Treggiari, Leo
> <le...@intel.com>
> 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: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
Re: Questions re: plugin variables
Posted by Marcel Kinard <cm...@gmail.com>.
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 <ka...@google.com> 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:
> http://plugins.cordova.io/#/package/com.phonegap.plugins.facebookconnect
>
> Relevant places in the code in cordova-lib:
> Where variables are checked during plugin add:
>
> https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L126
>
> https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plugman/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.
>
> https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plugman/util/config-changes.js#L368
>
>
> On Wed, Nov 5, 2014 at 5:28 PM, Treggiari, Leo <le...@intel.com>
> 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: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
Re: Questions re: plugin variables
Posted by Mark Koudritsky <ka...@google.com>.
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:
http://plugins.cordova.io/#/package/com.phonegap.plugins.facebookconnect
Relevant places in the code in cordova-lib:
Where variables are checked during plugin add:
https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L126
https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plugman/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.
https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/plugman/util/config-changes.js#L368
On Wed, Nov 5, 2014 at 5:28 PM, Treggiari, Leo <le...@intel.com>
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
>
>