Cordova-js enhanced platform APIs

[Drew Walters <de...@gmail.com>]

On a couple of occasions while working on integrating cordova-js
functionality into BlackBerry I've come across situations where
BlackBerry historically had enhanced API which was not available
across all platforms.  A great example of this is the Notification
API.  The common Notification API currently available in cordova-js
provides alert, confirm, beep and vibrate.  On BlackBerry (and
Android) platforms, support was added a while back to provide activity
and progress dialog creation/management [1].  With the existing
cordova-js implementation there doesn't seem to be a good way for a
platform to provide enhancements to a common API (adding to
window.notification).

Now, this could be solved in one of the two ways [2] we currently
handle platform overrides, but I would like to use the common API for
as much as possible and only inject the new API. I've coded up a
solution [3] to provide object merging through the builder which
allows the platforms to define the objects they would like to merge.
This allows a platform to make use of the common API but additionally
add enhancements to the exposed global object.  This seems to me a
little cleaner then option #2 in [2].

I believe this issue to be separate from the issue of providing a
proxy exec [4] as the issue I'm hoping to solve is allowing a platform
to expose API not common across platforms as opposed to overriding
common API.  Now, whether we should allow a platform to expose an API
that is not common is probably worth discussing, but we currently have
some historical compatibility issues we should strive to solve.  So,
some questions for discussion:

1. Should we allow platforms to expose API that is not common across
all platforms or should API always be in common and the platform coded
to fail gracefully if the API is not supported?
2. If we allow platform specific API, is the merge mechanism
preferable over options in [2]?

[1] https://github.com/apache/incubator-cordova-blackberry-webworks/blob/master/javascript/notification.js
[2] http://markmail.org/search/?q=drew+walters+exec&q=list%3Aorg.apache.incubator.callback-dev#query:drew%20walters%20exec%20list%3Aorg.apache.incubator.callback-dev+page:1+mid:eep4cruewmepbr4t+state:results
[3] https://github.com/deedubbu/incubator-cordova-js/commit/acb6263838f4b3182909ae775935d4d7f0bac286
[4] http://markmail.org/search/?q=drew+walters+exec&q=list%3Aorg.apache.incubator.callback-dev#query:drew%20walters%20exec%20list%3Aorg.apache.incubator.callback-dev+page:1+mid:p4v5bvri77qtbkpm+state:results

Re: Cordova-js enhanced platform APIs

[Filip Maj <fi...@adobe.com>]

>1. Should we allow platforms to expose API that is not common across
>all platforms or should API always be in common and the platform coded
>to fail gracefully if the API is not supported?

Seems like backwards compatibility is a common theme right now so I
suppose in the interim its acceptable to have platform-specific stuff.
However I would stress that we should strive really hard to factor this
stuff out as much as possible and instead put efforts into extending the
cordova API (down the road; post-1.6)

>2. If we allow platform specific API, is the merge mechanism
>preferable over options in [2]?

Yeah it's convenient, I don't mind it. More declarative than stacking
things into the initialize() method of the platform definition. Although
the include() method signature is getting a little hairy with us tacking
on extra boolean parameters ;D

>
>[1] 
>https://github.com/apache/incubator-cordova-blackberry-webworks/blob/maste
>r/javascript/notification.js
>[2] 
>http://markmail.org/search/?q=drew+walters+exec&q=list%3Aorg.apache.incuba
>tor.callback-dev#query:drew%20walters%20exec%20list%3Aorg.apache.incubator
>.callback-dev+page:1+mid:eep4cruewmepbr4t+state:results
>[3] 
>https://github.com/deedubbu/incubator-cordova-js/commit/acb6263838f4b31829
>09ae775935d4d7f0bac286
>[4] 
>http://markmail.org/search/?q=drew+walters+exec&q=list%3Aorg.apache.incuba
>tor.callback-dev#query:drew%20walters%20exec%20list%3Aorg.apache.incubator
>.callback-dev+page:1+mid:p4v5bvri77qtbkpm+state:results