Labs/Sprints/People: Difference between revisions

← Older edit

Labs/Sprints/People (view source)

Revision as of 08:57, 8 August 2009

2,126 bytes added , 8 August 2009

→‎API

Thunder

946

edits

@@ Line 27: / Line 27: @@
 == Structure ==
-There will be a single XPCOM component implemented in JavaScript, and an IDL file to go along with it.  The component can then be dropped into any extensions that need to use the interface, and eventually uplifted into Firefox.
+The backend store is implemented as a JS module.
 == API ==
-The component will provide a service which can be instantiated like so:
+First you'll need to import the module:
 <pre class="brush:js;toolbar:false;">
-let people = Components.classes["@labs.mozilla.org/people;1"]
+Components.utils.import("resource://people/modules/people.js");
-  .getService(Components.interfaces.IPeopleService);
 </pre>
-This service will support these API calls:
+Once imported you'll have access to these API calls:
 <pre class="brush:js;toolbar:false;">
-(guid) people.add(object)
+failed_person:object = People.add(person:object)
-(boolean) people.remove(guid)
+failed_person:object = People.update(person:object)
-(boolean) people.replace(object)
+success:bool = People.changeGUID(oldGUID:string, newGUID:string)
-  (array)  people.find(object)
+removed:int People.remove(attrs:object)
+[person:object, ...] =  People.find(attrs:object)
 </pre>
-In all cases the structure of the object will only be loosely defined, but could look something like this:
+Some of the calls also support multiple items passed in as arrays:
 <pre class="brush:js;toolbar:false;">
-{"firstname": "John",
+[failed:object, ...] = People.add([person:object, ...])
- "lastname": "Doe",
+[failed:object, ...] = People.update([person:object, ...])
- "identities": [
+[removed:int, ...] = People.remove([attrs:object, ...])
-   {"type": "gmail",
+</pre>
-    "firstname": "Johnnie",
-    "email": "jdoe@gmail.com", ...}
+Currently, the store uses transactions internally to add each person (because data is split up over multiple tables), so there is no public API for dealing with database transactions.  In the future, we may add this functionality.
- ]
+The object to pass in to <tt>add</tt> and <tt>update</tt> and returned by <tt>find</tt> look like the sample below. Currently, by default, we're storing a single [http://portablecontacts.net/draft-spec.html#schema Portable Contacts object] within the wrapper object.  Note that the schema for the 'default' document is contained in the <tt>default</tt> property of <tt>documentSchemas</tt>.  Be sure to verify the schema string, as the People store will not enforce adherence to Portable Contacts or any other schema.
+<pre>
+// People object
+{
+  // guid identifies this person, schema describes the wrapper object
+  guid: "af24d-fe488-ab748-b947f",
+  schema: "http://labs.mozilla.com/schemas/people/1",
+  // we pull out some fields for convenience.
+  // we only index fields we pull out.
+  displayName: "the foobinator",
+  givenName: "foo",
+  familyName: "bar",
+  documents: {
+    default: {
+      displayName: "the foobinator",
+      name{
+        givenName: "foo",
+        familyName: "bar"
+      },
+      emails: [
+        {value: "foo@gmail.com", type: "home"},
+        {value: "foo@yahoo.com", type: "work"},
+        {value: "bar@yahoo.com", type: "other"}
+      ]
+    }
+  },
+  documentSchemas: {
+    default: "http://portablecontacts.net/draft-spec.html"
+  }
 }
 </pre>
+=== Notifications ===
+Notifications will be sent for modifications to the people storage such as adding a new person. The subject of the notification is usually the GUID of the item. The following list shows the function and the notification topic sent with the subject data.
+<pre>
+add: "people-add" (guid)
+update: "people-update" (guid)
+remove: "people-before-remove" (guid)
+remove: "people-remove" (guid)
+changeGUID: "people-guid-change" ({ from: from, to: to })
+</pre>
+The notification for remove will notify first before removing the item and afterwards, so listeners of people-before-remove can still get the item before it disappears.
+If there are multiple items removed from a single remove call, each item will have its own notification.
 == Performance ==