348
edits
Labs/Contacts/ContentAPI: Difference between revisions
no edit summary
(Created page with 'The Contacts add-on adds a database of contact data to the browser, and allows web pages to request data from this database to use in web content. == Exposed Functions == In a …') |
No edit summary |
||
| Line 36: | Line 36: | ||
== Contact Schema == | == Contact Schema == | ||
The schema for Contacts is [http://portablecontacts.net/draft-spec.html#address_element|Portable Contacts version 1.0]. | |||
Importers will coerce data into this format when necessary. The most relevant fields for web pages that are consuming this data are: | |||
* displayName | |||
* name (with subproperties givenName and familyName) | |||
* emails (list; objects have type and value) | |||
* phoneNumbers (list; objects have type and value) | |||
* addresses (list; objects have streetAddress, locality, city, country, postalCode) | |||
* accounts (list; objects have domain, userid, username) | |||
* photos (list; objects have type and value; "thumbnail" and "profile" are canonical types) | |||
== Deltas from W3C Contacts API == | |||
The W3C Device APIs and Policy Working Group is working to standardize a Contacts API for web-enabled devices; you can [http://www.w3.org/TR/contacts-api/|read the latest draft here]. | |||
The Firefox implementation is lagging behind that API a bit; notable differences include: | |||
* W3C service point is navigator.service.contacts.find | |||
* W3C API puts <tt>fields</tt> first, and makes filter a subproperty of the <tt>options</tt> (fourth) argument | |||
* W3C API includes a multiple/single selector, and implies that the success callback will receive a single contact in the single case. | |||
* W3C API includes "save", "remove", and "clone" operations. | |||
* W3C API includes a number of more complex search operations (and weighting rules) than what is currently supported in the add-on. | |||
* W3C API includes error codes rather than strings for error callbacks | |||
* W3C API includes an "updatedSince" option to <tt>find</tt> | |||
== Experimental "Services" API == | |||
In version 0.4 and later of the Contacts add-on, experimental service support is included. | |||
The services API adds a "services" property to the Contact object, which has one or more functions attached to it that allow interaction with a contact's social web services. | |||
The implementation of these services is variable, depending on the web service involved, but the names and APIs of the service methods are designed to allow for a degree of interoperability and automatic discovery of a person's "social API". | |||
At present, the services API includes the following methods: | |||
* <tt>updates(callback)</tt> invokes the callback repeatedly, passing an array of objects representing recent updates. The properties of the update object are: | |||
* <tt>text</tt>: always present; a short text message | |||
* <tt>source</tt>: always present; the name of the service that provided the update | |||
* <tt>sourceLink</tt>: always present; a link to the page of the service that provided the update | |||
* <tt>link</tt>: optional; a link to more detail for the update | |||
* <tt>pictureCollectionsBy(callback)</tt> | |||