Differences between revisions 8 and 10 (spanning 2 versions)
Revision 8 as of 2013-02-22 23:28:22
Size: 7729
Editor: FilMaj
Comment: Linking more issues in JIRA to api audit
Revision 10 as of 2017-03-13 22:38:50
Size: 0
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= Core API Audit =

Good software, like a garden, needs maintenance. The Cordova Core API has a few weeds that need pulling!

== Accelerometer ==

 /!\ deprecated for http://dev.w3.org/geo/api/spec-source-orientation.html

Related issues:

  * Move tests to follow orientationchange spec? https://issues.apache.org/jira/browse/CB-286

== Camera ==

Related issues still outstanding:

  * Select multiple photos from the gallery (currently one is maximum). [[https://issues.apache.org/jira/browse/CB-1215]|CB-1215]]

== Capture ==

 /!\ deprecated for http://www.w3.org/TR/media-capture-api/

Related issues still outstanding:

  * Save to gallery after recording. [[https://issues.apache.org/jira/browse/CB-1371|CB-1371]]

== Compass ==

leave be but is this not covered by deviceorientation?

== Connection ==

 /!\ deprecated, now has 'bandwidth' attribute (way better?) http://dvcs.w3.org/hg/dap/raw-file/tip/network-api/Overview.html

== Contacts ==

 * http://dvcs.w3.org/hg/dap/raw-file/tip/contacts/Overview.html
 * http://www.w3.org/TR/contacts-api/
 * native picker

Related issues still outstanding:

 * What to do when you try to remove a contact that does not exist? [[https://issues.apache.org/jira/browse/CB-1143|CB-1143]]
 * Adding ability to specify sorting options. [[https://issues.apache.org/jira/browse/CB-346|CB-346]]
 * Adding ability to delete specific contact fields. [[https://issues.apache.org/jira/browse/CB-144|CB-144]]

== Device ==

 /!\ deprecated and move this gunk to cordova global (perhaps this belongs to capabilities api?)

Mailing list decided to move to async api and unify.

== Events ==

 /!\ deprecate battery stuff for its own plugin; leave the rest be

We may wish to consider implementing: http://www.html5rocks.com/en/tutorials/pagevisibility/intro/ for pause,resume,etc

== File ==

normalize paths:

  * Normalize return paths from capture API: [[https://issues.apache.org/jira/browse/CB-837|CB-837]]

== Geo ==

leave be

== Media ==

requires further audit (jesse doing this) (use html5 audio and/or normalize apis / add volume event) https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html

Also relevant is [[https://issues.apache.org/jira/browse/CB-1681|CB-1681]] - media.getCurrentPosition(time) and media.seekTo(time) have different units.

== Network ==

Move from navigator.network.connection -> navigator.connection. Re-work online/offline events to fire on window and document.body as per spec.

== Notification ==

 /!\ deprecated completely. alert/confirm in standard browser API, vibrate move to http://www.w3.org/TR/vibration/, kill beep


   - *Local Notifications*
      - System timers/alarms that can be set up to fire [periodically] in
      order to poke your app with some intent
      - No UI requirements, I think, just a "wake from sleep" feature
   - *StatusBar Notifications*
      - That awesome bar at the top: you can set up an icon, supply
      ticker-text, and/or configure drop down notification window items
      - Notifications may use sound/vibration/flashing lights to attract
      the attention of user when phone isn't in use
      - Users clicking notification window items will poke your app with
      some intent
      - Lots of features, vary between systems
   - *Push Notifications*
      - External cloud services send messages to your device in response to
      some server action/stimulus
      - Once a push arrives, action should likely be some combination of
      Local/StatusBar Notifications, but there are system limitations


   - Identify whats possible on each platform (initially android/ios)
   - Unify the api across platforms (as much as possible)
   - Use w3c spec for when possible:
      - http://www.w3.org/TR/notifications/
      - http://www.w3.org/TR/eventsource/ (or maybe not this one..)
   - Organize plugin documentation, and write up a single unified guide
   describing the various pieces and provide simple example
   - Potentially: prepare for move to core plugin, though that is not a
   direct goal

*Current state of the world: *(s/the world/phonegap-plugins/)


   - *LocalNotifications*
   - Needs documentation fixup
      - 6 months since proper update, but the code looks fine (at first
   - *PushNotifications*
   - Seems well maintained (Max Ogden +more)
      - Inspired by UA implementation (below) but seems to have a more
      robust api
      - Note from Max: no need for explicit notification api when app is in
      background but do when app is in foreground
   - *UAPushNotifications*
   - Urban Airship (http://urbanairship.com/)
      - We have no local implementation, just a TODO in repro, but found
      external: https://github.com/urbanairship/phonegap-ua-push
      - May be sufficient to just update our readme to point to that repo?
   - *StatusBarNotifier*
      - Seems to just change the top text of the *webview* status bar, so
      this plugin seems to not be a StatusBar notification as I defined above,
      more like an app "title" bar, so plugin seems misnamed.
      - Depends on 3rdparty plugin:
      - ios6 only, apparently?
   - *NotificationEx*
   - Not interesting, seems to just implement features that were removed
      from old cordova version


   - *LocalNotification*
   - Docs claim similar api to iOS version, but looks different (at first
      - Can't see how to register a callback (at first glance) -- so how is
      this useful? Generic wakeup?
      - 8 months since proper update, and the code looks like it needs work
   - *Push Notification*
   - There is no push notification plugin in the phonegap-plugin repo..
      - However, Max Ogden pointed me to external: GCM-Cordova (Google
      Cloud Messaging) https://github.com/marknutter/GCM-Cordova
         - GCM replaces C2DM as supported android push messaging service
      - Api is different than ios push plugin
      - Also Note from Max: you have to explicitly add things to the status
      bar as opposed to iOS where push notifications automatically get
      in the UI [for background apps I assume]
   - *StatusBarNotification*
   - Braden recently worked to clean this up to use w3c spec etc
      - I haven't scanned through it to see how much functionality it

*Open Questions*:

   - StatusBar Notifications: Intended for background services to notify a
   user to start some action (instead of just doing the action without users'
   explicit intent) -- so what does this mean for iOS without background
   - Are StatusBar notifications ever useful in foreground? Is that against
   some design principle? Leave that decision to the app developer? (fwiw:
   w3c spec seems to be a little vague, but no where does it say that
   notifications are to be used only while in background)
   - Push Notifications on ios: Can we intercept these when app is not in
   foreground, or must we just rely on default system behavior?

*Prioritizing Steps Forward:*

   1. StatusBar Notifications on iOS (w3c spec)
   2. Push Notifications on android
   3. Push Notifications on iOS (minor fixup/polyfill hopefully)
   4. Local Notifications on android

== Storage ==

 /!\ deprecate, the w3c doesnt want to support nor should we. file api and idb should care for all these use cases

Related issues:

  * Enabling Storage on cordova-mac: https://issues.apache.org/jira/browse/CB-456