View source for WebIntents/ContactsAPI

== Registration ==

This is assuming the new schema.org usage:

 <intent action="http://webintents.org/pick"
         type="http://schema.org/Person http://schema.org/Organization"
         encoding="application/json"
         ></intent>

== Client ==

This is assuming the new schema.org usage, but that we haven't yet switched to object literals.

  var intent = new Intent("http://webintents.org/pick",
                          "http://schema.org/Person",
                          "application/json",
                          null,
                          null,
                          { filter: "Bob", fields: ["name", "emails", "birthday"]});
  navigator.startActivity(intent, gotContacts);
  function gotContacts (data) {
      console.log(data); // logs an array of contacts as selected
  }

The same using object literal:

  var intent = new Intent({
                          action:    "http://webintents.org/pick",
                          type:      "http://schema.org/Person",
                          encoding:  "application/json",
                          extras:    { filter: "Bob", fields: ["name", "emails", "birthday"]}});

== Discussion ==

Actually the above makes use of encoding "application/json" when it really means that the client expects to get a JS object (in this case an array) which is a structured clone of the contact information. Presumably an alternative would be to use encoding "text/vcard" and get a blob of a vcard (or possibly a string in this case).

I think that that's wrong because in one case we're getting a blob of vcard and in the other we're getting an in-memory structure, when in fact we logically should be getting a blob of JSON — JSON is being treated specially. Furthermore, if the fields had included pictures, ideally we'd want them to be Blobs where in fact if they were application/json they'd have to be serialised as data URIs (or some similar option). So the application/json is a lie.

Alternative proposal: when no encoding parameter is specified, this means that a structured clone will always be passed. When the encoding is passed, it means that a Blob (or array of Blobs?) will always be passed. This leads to this alternative variant (that is both more semantically correct and shorter):


 <intent action="http://webintents.org/pick"
         type="http://schema.org/Person http://schema.org/Organization"
         ></intent>

  var intent = new Intent({
                          action:    "http://webintents.org/pick",
                          type:      "http://schema.org/Person",
                          extras:    { filter: "Bob", fields: ["name", "emails", "birthday"]}});