Plugin discussion: Feature detection

[Rob Paveza <Ro...@microsoft.com>]

We chatted briefly about this at the hangout last week, and I wanted to continue on the discussion.  I gave the example that the "Quirks" section of CameraOptions [1] is longer than the actual API documentation.  I like to pick on the Camera plugin because it's one of the most-used and is very well-documented, so its holes are easy to understand.

I looked at a request to, for example, support the <plugin> element within a <platform> element in config.xml.  When we drilled down into the request, it was because the plugin wasn't well-supported on Windows, so the developer wanted to be able to do feature detection and bypass using the plugin there.  Presently, Cordova.js doesn't support this; the proxy doesn't have an opportunity to talk to native until the `deviceready` event, at which point, mutating the public API surface of the proxy would result in a race condition (because you're not sure who subscribed to `deviceready` first).

I think it's important to note that **how the API can support feature detection should be up to the plugin author**.  If the plugin is trying to mimic a W3C standard, then it can do so; if it's just trying to fill a feature gap, it can do that, too.  The plugin developer can choose what fits best.

==Proposal==
 - I'll make a change to Cordova.js that will create a new event for plugins to listen to.  This will delay the invocation of `deviceready` until all plugins have signaled completion (we'll avoid breaking compatibility by having plugins opt-in to this behavior; if they don't opt in, we'll treat them like they don't need to do anything).  Once the plugin initialization code has been run and the plugins have signaled readiness, we'll then fire `deviceready`.
 - I'd also like to go through the plugins at least in mobilespec and make some targeted proposals about where we can refactor to improve feature-detectability.  The File Plugin is tough because it's standards-based on a standard that is defunct, but the Camera plugin might have some opportunities, as well as Vibration, etc (e.g., vibration is supported on Windows mobile devices, but not on desktop PCs).

== Guiding Principles ==
 - Feature detection should be based on the availability of the platform API, not the availability of the platform to do the work.  
  - For example, if we created a Printer plugin, and the device can support printing but no printers are attached, then the print() API should be available.  
  - In such a case, calling print() should result in a runtime error.  The plugin author should provide a way to query for attached printers.
  - This allows for a printer to be attached at a later time.
 - Features should be in some way able to be queried by code at runtime.
  - Whether that's via a "foo.hasFeature(bar)" method or "if (foo.bar)" truthy check, we should try our best to follow web principles in making these decisions and enable it to be similar to known practices on the web.

Looking forward to hearing your thoughts...
-Rob

[1] https://github.com/apache/cordova-plugin-camera#cameraoptions

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org

Re: Plugin discussion: Feature detection

[Carlos Santana <cs...@gmail.com>]

No objections, move forward and create a Github Issue :-p

- Carlos
Sent from my iPhone

> On Aug 11, 2015, at 7:56 PM, Shazron <sh...@gmail.com> wrote:
> 
> If no one has any objections, there should be a JIRA issue tracking this
> task so it doesn't get lost or forgotten.
> 
> On Thu, Jul 23, 2015 at 6:49 AM, Carlos Santana <cs...@gmail.com>
> wrote:
> 
>> +1 cordova-js have the logic to handle this at bootstrap, it's a matter of
>> staring for a few minutes to see what are the entry points that Jesse
>> describe.
>> 
>> For the plug and play scenario, where you plugin something way after
>> deviceready/bootstrap then something dynamic to query for the capabilities
>> like Jesse describe
>> 
>> Let's keep the two use cases separate and do not cross the streams :-),
>> fix each use case at a time
>> 
>>> On Tue, Jul 21, 2015 at 6:17 PM Jesse <pu...@gmail.com> wrote:
>>> 
>>> There are a couple different ways to go about this, but ultimately the
>>> mechanisms are already there.
>>> 
>>> 1. WaitForInit
>>> If you look at the cordova-device plugin, it pre-populates data about the
>>> device it is running on, and this info is available when the deviceready
>>> event fires.
>>> Essentially the plugin creates a channel, and specifies that this channel
>>> must fire BEFORE the deviceready channel can fire, via the call
>>> channel.waitForInitialization('onCordovaInfoReady'); //[1]
>>> 
>>> 2. addConstructor
>>> The window.cordova object defines an addConstructor method to allow a
>>> plugin to do some pre-deviceready work.
>>> All functions passed in to cordova.addConstructor will be called at the
>>> 'cordovaready' stage which is guaranteed to happen after 'nativeready'
>> and
>>> before 'deviceready'  [2]
>>> 
>>> Another approach may be to add a getDeviceCapabilites async call to a
>>> plugin like Camera that has many varied capabilities depending on where
>> it
>>> is running.  We could simply instruct users to call this method ( after
>>> deviceready ) to know for certain what capabilities are available.  The
>>> plugin (js) could also cache this info so later calls would not require a
>>> round trip. This would allow the app to be active as soon as possible,
>> and
>>> place the responsibility on the app developer, especially relevant if the
>>> camera api is a small subset of the functionality of the app, and the
>>> capabilities are not essential at launch time.
>>> 
>>> 
>>> [1]
>> https://github.com/apache/cordova-plugin-device/blob/master/www/device.js#L28
>>> [2] https://github.com/apache/cordova-js/blob/master/src/cordova.js#L233
>>> 
>>> 
>>> 
>>> 
>>> My team is hiring!
>>> @purplecabbage
>>> risingj.com
>>> 
>>> On Mon, Jul 20, 2015 at 11:34 AM, Rob Paveza <Ro...@microsoft.com>
>>> wrote:
>>> 
>>>> We chatted briefly about this at the hangout last week, and I wanted to
>>>> continue on the discussion.  I gave the example that the "Quirks"
>> section
>>>> of CameraOptions [1] is longer than the actual API documentation.  I
>> like
>>>> to pick on the Camera plugin because it's one of the most-used and is
>>> very
>>>> well-documented, so its holes are easy to understand.
>>>> 
>>>> I looked at a request to, for example, support the <plugin> element
>>> within
>>>> a <platform> element in config.xml.  When we drilled down into the
>>> request,
>>>> it was because the plugin wasn't well-supported on Windows, so the
>>>> developer wanted to be able to do feature detection and bypass using
>> the
>>>> plugin there.  Presently, Cordova.js doesn't support this; the proxy
>>>> doesn't have an opportunity to talk to native until the `deviceready`
>>>> event, at which point, mutating the public API surface of the proxy
>> would
>>>> result in a race condition (because you're not sure who subscribed to
>>>> `deviceready` first).
>>>> 
>>>> I think it's important to note that **how the API can support feature
>>>> detection should be up to the plugin author**.  If the plugin is trying
>>> to
>>>> mimic a W3C standard, then it can do so; if it's just trying to fill a
>>>> feature gap, it can do that, too.  The plugin developer can choose what
>>>> fits best.
>>>> 
>>>> ==Proposal==
>>>> - I'll make a change to Cordova.js that will create a new event for
>>>> plugins to listen to.  This will delay the invocation of `deviceready`
>>>> until all plugins have signaled completion (we'll avoid breaking
>>>> compatibility by having plugins opt-in to this behavior; if they don't
>>> opt
>>>> in, we'll treat them like they don't need to do anything).  Once the
>>> plugin
>>>> initialization code has been run and the plugins have signaled
>> readiness,
>>>> we'll then fire `deviceready`.
>>>> - I'd also like to go through the plugins at least in mobilespec and
>>> make
>>>> some targeted proposals about where we can refactor to improve
>>>> feature-detectability.  The File Plugin is tough because it's
>>>> standards-based on a standard that is defunct, but the Camera plugin
>>> might
>>>> have some opportunities, as well as Vibration, etc (e.g., vibration is
>>>> supported on Windows mobile devices, but not on desktop PCs).
>>>> 
>>>> == Guiding Principles ==
>>>> - Feature detection should be based on the availability of the
>> platform
>>>> API, not the availability of the platform to do the work.
>>>>  - For example, if we created a Printer plugin, and the device can
>>>> support printing but no printers are attached, then the print() API
>>> should
>>>> be available.
>>>>  - In such a case, calling print() should result in a runtime error.
>>> The
>>>> plugin author should provide a way to query for attached printers.
>>>>  - This allows for a printer to be attached at a later time.
>>>> - Features should be in some way able to be queried by code at
>> runtime.
>>>>  - Whether that's via a "foo.hasFeature(bar)" method or "if (foo.bar)"
>>>> truthy check, we should try our best to follow web principles in making
>>>> these decisions and enable it to be similar to known practices on the
>>> web.
>>>> 
>>>> Looking forward to hearing your thoughts...
>>>> -Rob
>>>> 
>>>> [1] https://github.com/apache/cordova-plugin-camera#cameraoptions
>>>> 
>>>> ---------------------------------------------------------------------
>>>> 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: Plugin discussion: Feature detection

[Shazron <sh...@gmail.com>]

If no one has any objections, there should be a JIRA issue tracking this
task so it doesn't get lost or forgotten.

On Thu, Jul 23, 2015 at 6:49 AM, Carlos Santana <cs...@gmail.com>
wrote:

> +1 cordova-js have the logic to handle this at bootstrap, it's a matter of
> staring for a few minutes to see what are the entry points that Jesse
> describe.
>
> For the plug and play scenario, where you plugin something way after
> deviceready/bootstrap then something dynamic to query for the capabilities
> like Jesse describe
>
> Let's keep the two use cases separate and do not cross the streams :-),
>  fix each use case at a time
>
> On Tue, Jul 21, 2015 at 6:17 PM Jesse <pu...@gmail.com> wrote:
>
> > There are a couple different ways to go about this, but ultimately the
> > mechanisms are already there.
> >
> > 1. WaitForInit
> > If you look at the cordova-device plugin, it pre-populates data about the
> > device it is running on, and this info is available when the deviceready
> > event fires.
> > Essentially the plugin creates a channel, and specifies that this channel
> > must fire BEFORE the deviceready channel can fire, via the call
> > channel.waitForInitialization('onCordovaInfoReady'); //[1]
> >
> > 2. addConstructor
> > The window.cordova object defines an addConstructor method to allow a
> > plugin to do some pre-deviceready work.
> > All functions passed in to cordova.addConstructor will be called at the
> > 'cordovaready' stage which is guaranteed to happen after 'nativeready'
> and
> > before 'deviceready'  [2]
> >
> > Another approach may be to add a getDeviceCapabilites async call to a
> > plugin like Camera that has many varied capabilities depending on where
> it
> > is running.  We could simply instruct users to call this method ( after
> > deviceready ) to know for certain what capabilities are available.  The
> > plugin (js) could also cache this info so later calls would not require a
> > round trip. This would allow the app to be active as soon as possible,
> and
> > place the responsibility on the app developer, especially relevant if the
> > camera api is a small subset of the functionality of the app, and the
> > capabilities are not essential at launch time.
> >
> >
> > [1]
> >
> >
> https://github.com/apache/cordova-plugin-device/blob/master/www/device.js#L28
> > [2] https://github.com/apache/cordova-js/blob/master/src/cordova.js#L233
> >
> >
> >
> >
> > My team is hiring!
> > @purplecabbage
> > risingj.com
> >
> > On Mon, Jul 20, 2015 at 11:34 AM, Rob Paveza <Ro...@microsoft.com>
> > wrote:
> >
> > > We chatted briefly about this at the hangout last week, and I wanted to
> > > continue on the discussion.  I gave the example that the "Quirks"
> section
> > > of CameraOptions [1] is longer than the actual API documentation.  I
> like
> > > to pick on the Camera plugin because it's one of the most-used and is
> > very
> > > well-documented, so its holes are easy to understand.
> > >
> > > I looked at a request to, for example, support the <plugin> element
> > within
> > > a <platform> element in config.xml.  When we drilled down into the
> > request,
> > > it was because the plugin wasn't well-supported on Windows, so the
> > > developer wanted to be able to do feature detection and bypass using
> the
> > > plugin there.  Presently, Cordova.js doesn't support this; the proxy
> > > doesn't have an opportunity to talk to native until the `deviceready`
> > > event, at which point, mutating the public API surface of the proxy
> would
> > > result in a race condition (because you're not sure who subscribed to
> > > `deviceready` first).
> > >
> > > I think it's important to note that **how the API can support feature
> > > detection should be up to the plugin author**.  If the plugin is trying
> > to
> > > mimic a W3C standard, then it can do so; if it's just trying to fill a
> > > feature gap, it can do that, too.  The plugin developer can choose what
> > > fits best.
> > >
> > > ==Proposal==
> > >  - I'll make a change to Cordova.js that will create a new event for
> > > plugins to listen to.  This will delay the invocation of `deviceready`
> > > until all plugins have signaled completion (we'll avoid breaking
> > > compatibility by having plugins opt-in to this behavior; if they don't
> > opt
> > > in, we'll treat them like they don't need to do anything).  Once the
> > plugin
> > > initialization code has been run and the plugins have signaled
> readiness,
> > > we'll then fire `deviceready`.
> > >  - I'd also like to go through the plugins at least in mobilespec and
> > make
> > > some targeted proposals about where we can refactor to improve
> > > feature-detectability.  The File Plugin is tough because it's
> > > standards-based on a standard that is defunct, but the Camera plugin
> > might
> > > have some opportunities, as well as Vibration, etc (e.g., vibration is
> > > supported on Windows mobile devices, but not on desktop PCs).
> > >
> > > == Guiding Principles ==
> > >  - Feature detection should be based on the availability of the
> platform
> > > API, not the availability of the platform to do the work.
> > >   - For example, if we created a Printer plugin, and the device can
> > > support printing but no printers are attached, then the print() API
> > should
> > > be available.
> > >   - In such a case, calling print() should result in a runtime error.
> > The
> > > plugin author should provide a way to query for attached printers.
> > >   - This allows for a printer to be attached at a later time.
> > >  - Features should be in some way able to be queried by code at
> runtime.
> > >   - Whether that's via a "foo.hasFeature(bar)" method or "if (foo.bar)"
> > > truthy check, we should try our best to follow web principles in making
> > > these decisions and enable it to be similar to known practices on the
> > web.
> > >
> > > Looking forward to hearing your thoughts...
> > > -Rob
> > >
> > > [1] https://github.com/apache/cordova-plugin-camera#cameraoptions
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
> > > For additional commands, e-mail: dev-help@cordova.apache.org
> > >
> > >
> >
>

Re: Plugin discussion: Feature detection

[Carlos Santana <cs...@gmail.com>]

+1 cordova-js have the logic to handle this at bootstrap, it's a matter of
staring for a few minutes to see what are the entry points that Jesse
describe.

For the plug and play scenario, where you plugin something way after
deviceready/bootstrap then something dynamic to query for the capabilities
like Jesse describe

Let's keep the two use cases separate and do not cross the streams :-),
 fix each use case at a time

On Tue, Jul 21, 2015 at 6:17 PM Jesse <pu...@gmail.com> wrote:

> There are a couple different ways to go about this, but ultimately the
> mechanisms are already there.
>
> 1. WaitForInit
> If you look at the cordova-device plugin, it pre-populates data about the
> device it is running on, and this info is available when the deviceready
> event fires.
> Essentially the plugin creates a channel, and specifies that this channel
> must fire BEFORE the deviceready channel can fire, via the call
> channel.waitForInitialization('onCordovaInfoReady'); //[1]
>
> 2. addConstructor
> The window.cordova object defines an addConstructor method to allow a
> plugin to do some pre-deviceready work.
> All functions passed in to cordova.addConstructor will be called at the
> 'cordovaready' stage which is guaranteed to happen after 'nativeready' and
> before 'deviceready'  [2]
>
> Another approach may be to add a getDeviceCapabilites async call to a
> plugin like Camera that has many varied capabilities depending on where it
> is running.  We could simply instruct users to call this method ( after
> deviceready ) to know for certain what capabilities are available.  The
> plugin (js) could also cache this info so later calls would not require a
> round trip. This would allow the app to be active as soon as possible, and
> place the responsibility on the app developer, especially relevant if the
> camera api is a small subset of the functionality of the app, and the
> capabilities are not essential at launch time.
>
>
> [1]
>
> https://github.com/apache/cordova-plugin-device/blob/master/www/device.js#L28
> [2] https://github.com/apache/cordova-js/blob/master/src/cordova.js#L233
>
>
>
>
> My team is hiring!
> @purplecabbage
> risingj.com
>
> On Mon, Jul 20, 2015 at 11:34 AM, Rob Paveza <Ro...@microsoft.com>
> wrote:
>
> > We chatted briefly about this at the hangout last week, and I wanted to
> > continue on the discussion.  I gave the example that the "Quirks" section
> > of CameraOptions [1] is longer than the actual API documentation.  I like
> > to pick on the Camera plugin because it's one of the most-used and is
> very
> > well-documented, so its holes are easy to understand.
> >
> > I looked at a request to, for example, support the <plugin> element
> within
> > a <platform> element in config.xml.  When we drilled down into the
> request,
> > it was because the plugin wasn't well-supported on Windows, so the
> > developer wanted to be able to do feature detection and bypass using the
> > plugin there.  Presently, Cordova.js doesn't support this; the proxy
> > doesn't have an opportunity to talk to native until the `deviceready`
> > event, at which point, mutating the public API surface of the proxy would
> > result in a race condition (because you're not sure who subscribed to
> > `deviceready` first).
> >
> > I think it's important to note that **how the API can support feature
> > detection should be up to the plugin author**.  If the plugin is trying
> to
> > mimic a W3C standard, then it can do so; if it's just trying to fill a
> > feature gap, it can do that, too.  The plugin developer can choose what
> > fits best.
> >
> > ==Proposal==
> >  - I'll make a change to Cordova.js that will create a new event for
> > plugins to listen to.  This will delay the invocation of `deviceready`
> > until all plugins have signaled completion (we'll avoid breaking
> > compatibility by having plugins opt-in to this behavior; if they don't
> opt
> > in, we'll treat them like they don't need to do anything).  Once the
> plugin
> > initialization code has been run and the plugins have signaled readiness,
> > we'll then fire `deviceready`.
> >  - I'd also like to go through the plugins at least in mobilespec and
> make
> > some targeted proposals about where we can refactor to improve
> > feature-detectability.  The File Plugin is tough because it's
> > standards-based on a standard that is defunct, but the Camera plugin
> might
> > have some opportunities, as well as Vibration, etc (e.g., vibration is
> > supported on Windows mobile devices, but not on desktop PCs).
> >
> > == Guiding Principles ==
> >  - Feature detection should be based on the availability of the platform
> > API, not the availability of the platform to do the work.
> >   - For example, if we created a Printer plugin, and the device can
> > support printing but no printers are attached, then the print() API
> should
> > be available.
> >   - In such a case, calling print() should result in a runtime error.
> The
> > plugin author should provide a way to query for attached printers.
> >   - This allows for a printer to be attached at a later time.
> >  - Features should be in some way able to be queried by code at runtime.
> >   - Whether that's via a "foo.hasFeature(bar)" method or "if (foo.bar)"
> > truthy check, we should try our best to follow web principles in making
> > these decisions and enable it to be similar to known practices on the
> web.
> >
> > Looking forward to hearing your thoughts...
> > -Rob
> >
> > [1] https://github.com/apache/cordova-plugin-camera#cameraoptions
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
> > For additional commands, e-mail: dev-help@cordova.apache.org
> >
> >
>

Re: Plugin discussion: Feature detection

[Jesse <pu...@gmail.com>]

There are a couple different ways to go about this, but ultimately the
mechanisms are already there.

1. WaitForInit
If you look at the cordova-device plugin, it pre-populates data about the
device it is running on, and this info is available when the deviceready
event fires.
Essentially the plugin creates a channel, and specifies that this channel
must fire BEFORE the deviceready channel can fire, via the call
channel.waitForInitialization('onCordovaInfoReady'); //[1]

2. addConstructor
The window.cordova object defines an addConstructor method to allow a
plugin to do some pre-deviceready work.
All functions passed in to cordova.addConstructor will be called at the
'cordovaready' stage which is guaranteed to happen after 'nativeready' and
before 'deviceready'  [2]

Another approach may be to add a getDeviceCapabilites async call to a
plugin like Camera that has many varied capabilities depending on where it
is running.  We could simply instruct users to call this method ( after
deviceready ) to know for certain what capabilities are available.  The
plugin (js) could also cache this info so later calls would not require a
round trip. This would allow the app to be active as soon as possible, and
place the responsibility on the app developer, especially relevant if the
camera api is a small subset of the functionality of the app, and the
capabilities are not essential at launch time.


[1]
https://github.com/apache/cordova-plugin-device/blob/master/www/device.js#L28
[2] https://github.com/apache/cordova-js/blob/master/src/cordova.js#L233




My team is hiring!
@purplecabbage
risingj.com

On Mon, Jul 20, 2015 at 11:34 AM, Rob Paveza <Ro...@microsoft.com>
wrote:

> We chatted briefly about this at the hangout last week, and I wanted to
> continue on the discussion.  I gave the example that the "Quirks" section
> of CameraOptions [1] is longer than the actual API documentation.  I like
> to pick on the Camera plugin because it's one of the most-used and is very
> well-documented, so its holes are easy to understand.
>
> I looked at a request to, for example, support the <plugin> element within
> a <platform> element in config.xml.  When we drilled down into the request,
> it was because the plugin wasn't well-supported on Windows, so the
> developer wanted to be able to do feature detection and bypass using the
> plugin there.  Presently, Cordova.js doesn't support this; the proxy
> doesn't have an opportunity to talk to native until the `deviceready`
> event, at which point, mutating the public API surface of the proxy would
> result in a race condition (because you're not sure who subscribed to
> `deviceready` first).
>
> I think it's important to note that **how the API can support feature
> detection should be up to the plugin author**.  If the plugin is trying to
> mimic a W3C standard, then it can do so; if it's just trying to fill a
> feature gap, it can do that, too.  The plugin developer can choose what
> fits best.
>
> ==Proposal==
>  - I'll make a change to Cordova.js that will create a new event for
> plugins to listen to.  This will delay the invocation of `deviceready`
> until all plugins have signaled completion (we'll avoid breaking
> compatibility by having plugins opt-in to this behavior; if they don't opt
> in, we'll treat them like they don't need to do anything).  Once the plugin
> initialization code has been run and the plugins have signaled readiness,
> we'll then fire `deviceready`.
>  - I'd also like to go through the plugins at least in mobilespec and make
> some targeted proposals about where we can refactor to improve
> feature-detectability.  The File Plugin is tough because it's
> standards-based on a standard that is defunct, but the Camera plugin might
> have some opportunities, as well as Vibration, etc (e.g., vibration is
> supported on Windows mobile devices, but not on desktop PCs).
>
> == Guiding Principles ==
>  - Feature detection should be based on the availability of the platform
> API, not the availability of the platform to do the work.
>   - For example, if we created a Printer plugin, and the device can
> support printing but no printers are attached, then the print() API should
> be available.
>   - In such a case, calling print() should result in a runtime error.  The
> plugin author should provide a way to query for attached printers.
>   - This allows for a printer to be attached at a later time.
>  - Features should be in some way able to be queried by code at runtime.
>   - Whether that's via a "foo.hasFeature(bar)" method or "if (foo.bar)"
> truthy check, we should try our best to follow web principles in making
> these decisions and enable it to be similar to known practices on the web.
>
> Looking forward to hearing your thoughts...
> -Rob
>
> [1] https://github.com/apache/cordova-plugin-camera#cameraoptions
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
> For additional commands, e-mail: dev-help@cordova.apache.org
>
>