canmove, Confirmed users
2,887
edits
WebAPI/ContactsAPI: Difference between revisions
Jump to navigation
Jump to search
reorder intro to make more sense, move FAQ to end, add FAQ: Is the name property a composition or something users enter
No edit summary |
(reorder intro to make more sense, move FAQ to end, add FAQ: Is the name property a composition or something users enter) |
||
| Line 1: | Line 1: | ||
= Contacts API specification = | |||
ContactsAPI is also known as WebContacts (or Contacts+). | |||
The DAP WG (W3C) has specification sharing this proposal goal [1] | == Goals == | ||
Provide read/write DOM API access to the device address book, and the contacts contained therein with a simple minimal API that has a high-degree of interoperability with both device address books and commonly published web contact information (vCard/hCard). - [[User:Tantek|Tantek]] | |||
== W3C DAP work == | |||
The DAP WG (W3C) has specification sharing some of the goals of this proposal goal [1]. | |||
[1] http://dev.w3.org/2009/dap/contacts/ | [1] http://dev.w3.org/2009/dap/contacts/ | ||
For the moment, the Contacts API proposal differs from the DAP specification in some key ways: | |||
* simplified / flattened properties/interfaces/API per lessons learned with the development of both [[vCard4]] and [[hCard]] (including [[hCard 2]]) | |||
* read/write API explicitly designed to avoid multi-access write corruption | |||
== Status == | == Status == | ||
| Line 104: | Line 110: | ||
* ContactAddress 'geo' property components 'latitude', 'longitude' and additional 'altitude' from GeoLocation API | * ContactAddress 'geo' property components 'latitude', 'longitude' and additional 'altitude' from GeoLocation API | ||
* Contact 'gender' property components 'sex', 'gender-identity' (from vCard4/hCard2 in particular) | * Contact 'gender' property components 'sex', 'gender-identity' (from vCard4/hCard2 in particular) | ||
== Example == | == Example == | ||
| Line 152: | Line 140: | ||
newContact.remove(successCb, errorCb); | newContact.remove(successCb, errorCb); | ||
navigator.mozContacts.clear(successCb, errorCb); | navigator.mozContacts.clear(successCb, errorCb); | ||
== Considered changes == | |||
* ''mozContacts'' object might move to window.navigator.device; | |||
* more Contact attributes (from Address Book UIs of BlackBerry - BB, iPhone/iTouch - iOS) | |||
** ringtone (BB, iOS) | |||
** job-title (BB, iOS) | |||
** messagetone (BB) | |||
** phonetic-given-name (iOS) | |||
** phonetic-family-name (iOS) | |||
** formal-name (per suggestion from Jonas), like name, but with all "honorable so and so" etc. included as you would formally address or introduce someone. needs examples of publication on the web, and/or device address books that actually include such a field (haven't seen one yet). | |||
== FAQ == | |||
=== Why are givenName familyName arrays instead of optional === | |||
* could use clarification of why a number of fields are arrays instead of optional DOMString. e.g. givenName, familyName. Those seem like 0-or-1 cases, not lists. | |||
** '''In short, i18n.''' Experience with vCard3 and hCard with international content has shown that multiple different languages/cultures have multiple given names and family names, and thus the change was made in [[vCard4]] to make these multivalued. - [[User:Tantek|Tantek]] 10:37, 25 October 2011 (PDT) | |||
=== Why are flattened adr properties arrays instead of optional === | |||
* could use clarification of why a number of fields are arrays instead of optional DOMString. e.g. fields of the flattened adr. Those seem like 0-or-1 cases, not lists. | |||
** '''In short, simplification and i18n.''' The multivalued adr properties are a result of both lack of use / common mis-use of post-office-box and extended-address properties (such data is more often/reliably shoved into multiple lines of street-address) and countries having multiple lines/values for street-address and/or locality/region. - [[User:Tantek|Tantek]] 10:37, 25 October 2011 (PDT) | |||
=== Is the name property a composition or something users enter === | |||
* Is the name property a composition of given and family name or is it something users can enter? | |||
** '''In short, name is 'fn' and can be entered.''' The 'name' property is the replacement for 'fn' from vCard/hCard (what the DAP folks call 'displayName' or similar). This is an explicit renaming (to 'name') that multiple parties have independently done, and thus is being adopted in [[hCard 2]] and thus we are adopting as well in the ContactsAPI. The 'name' property is something users can enter, DAP calls it 'displayName" or something like that. | |||