- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 14 Jan 2010 17:34:29 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv6640
Modified Files:
Overview.html
Log Message:
Update based on feedback from the group:
- Contact.addresses becomes of a ContactAddress Array type to align with the ongoing definition in W3C Geolocation WG.
- Options accounted for in 'Contact Search Processing Rules' section.
- ContactOptions.group becomes a boolean type.
- Examples updated
- Examples shown on navigator.service object while this discussion is ongoing.
- Contacts.create updated to allow more properties to be provided at object creation.
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -d -r1.22 -r1.23
--- Overview.html 18 Dec 2009 13:31:03 -0000 1.22
+++ Overview.html 14 Jan 2010 17:34:27 -0000 1.23
@@ -52,19 +52,20 @@
</p>
<pre class='example sh_javascript_dom'>function successContactFindCallback(contacts) {
// do something with resulting contact objects
+ // for (var i in contacts) alert(contacts[i].name);
// ...
}
-function genericErrorCB(error) {
+function generalErrorCB(error) {
// do something with resulting errors
// alert(error.code);
// ...
}
// Perform an address book search
-navigator.device.contacts.find( {name: 'Bob'},
+navigator.service.contacts.find( {name: 'Bob'},
successContactFindCallback,
- genericErrorCB );</pre>
+ generalErrorCB );</pre>
</div>
<div>
<p>
@@ -73,7 +74,7 @@
<pre class='example sh_javascript_dom'>// previous example follow-on...
// Create new contact
-var myContact = navigator.device.contacts.create('Mr. Robert Smith Jr');
+var myContact = navigator.service.contacts.create({name: 'Mr. Robert Smith Jr'});
// Add additional contact attributes as required...
// myContact.nicknames.push('bobby');</pre>
@@ -90,7 +91,7 @@
}
// Add new contact
-myContact.save(successContactCallback, genericErrorCB);</pre>
+myContact.save(successContactCallback, generalErrorCB);</pre>
</div>
<div>
@@ -103,7 +104,7 @@
myContact.phones.push({types: ['home'], value: '+440000000002'});
// Update existing contact
-myContact.save(successContactCallback, genericErrorCB);</pre>
+myContact.save(successContactCallback, generalErrorCB);</pre>
</div>
<div>
@@ -113,7 +114,7 @@
<pre class='example sh_javascript_dom'>// previous example follow-on...
// Remove existing contact
-myContact.remove(successContactCallback, genericErrorCB);</pre>
+myContact.remove(successContactCallback, generalErrorCB);</pre>
</div>
@@ -220,17 +221,17 @@
<section>
<h2>API Description</h2>
<section>
- <h2><a>DeviceContacts</a> interface</h2>
+ <h2><a>ServiceContacts</a> interface</h2>
-<p class='issue'>The actual object of which the API will be hanging off is still under discussion (e.g. directly from <code>navigator</code> vs from <code>navigator.device</code>); see <a href="http://www.w3.org/2009/dap/track/issues/44">ISSUE-44: What do APIs hang off of?</a>?</p>
+<p class='issue'>The actual object of which the API will be hanging off is still under discussion (e.g. <code>navigator.service</code> vs from <code>navigator.device</code>); see <a href="http://www.w3.org/2009/dap/track/issues/67">ISSUE-67</a></p>
<p>
- The <a href='#devicecontacts-interface'><code>DeviceContacts</code></a> interface is exposed on the <code>navigator.device</code> object, as defined in [[CORE-DEVICE]].
+ The <a href='#servicecontacts-interface'><code>ServiceContacts</code></a> interface is exposed on the <code>navigator.service</code> object, as defined in [[CORE-DEVICE]].
</p>
- <div class='idl' title='Device implements DeviceContacts'></div>
+ <div class='idl' title='Service implements ServiceContacts'></div>
- <dl title='[NoInterfaceObject] interface DeviceContacts' class='idl'>
+ <dl title='[NoInterfaceObject] interface ServiceContacts' class='idl'>
<dt>
readonly attribute Contacts contacts
</dt>
@@ -274,10 +275,10 @@
<dl class='parameters'>
<dt>
- DOMString name
+ ContactProperties attributes
</dt>
<dd>
- The name of the content to add to the resulting object. This is the only mandatory attribute for creating a new <a href='#contact-interface'><code>Contact</code></a> object.
+ The attributes to assign to the resulting object.
</dd>
</dl>
</dd>
@@ -314,7 +315,7 @@
Function to call when the asynchronous operation completes
</dd>
<dt>
- optional ErrorCB errorCB
+ optional ContactErrorCB? errorCB
</dt>
<dd>
Function to call when the asynchronous operation fails.
@@ -372,7 +373,7 @@
<p>Add or update (as appropriate) the current <a href="#contact-interface"><code>Contact</code></a> object to the <a href="#contacts-interface"><code>Contacts</code></a>.</p>
<p>
- In the case that the <a href='#widl-ContactProperties-name'><code>name</code></a> attribute is <code>null</code> and this method is invoked, an <a href='#errorcallback-interface'><code>ErrorCB</code></a> MUST be
+ In the case that the <a href='#widl-ContactProperties-name'><code>name</code></a> attribute is <code>null</code> and this method is invoked, an <a href='#contacterrorcb-interface'><code>ContactErrorCB</code></a> MUST be
triggered as part of the <a>save contact process</a>. This error MUST consist of a <a href="#contacterror-interface"><code>ContactError</code></a> object with a <a href='#widl-ContactError-code'><code>code</code></a> of
<a href='#widl-ContactError-CONTACT_INVALID_ERROR'><code>ContactError::CONTACT_INVALID_ERROR</code></a>.
</p>
@@ -399,7 +400,7 @@
Function to call when the asynchronous operation completes
</dd>
<dt>
- optional ErrorCB errorCB
+ optional ContactErrorCB? errorCB
</dt>
<dd>
Function to call when the asynchronous operation fails.
@@ -414,7 +415,7 @@
<p>Remove the current contact from the address book.</p>
<p>
- In the case that the current <a href='#widl-Contact-id'><code>id</code></a> attribute is <code>NULL</code> and this method is invoked, an <a href="#errorcallback-interface"><code>ErrorCB</code></a> MUST be
+ In the case that the current <a href='#widl-Contact-id'><code>id</code></a> attribute is <code>NULL</code> and this method is invoked, a <a href='#contacterrorcb-interface'><code>ContactErrorCB</code></a> MUST be
triggered as part of the <a>remove contact process</a>. This error MUST consist of a <a href="#contacterror-interface"><code>ContactError</code></a> object with a <a href='#widl-ContactError-code'><code>code</code></a> of
<a href='#widl-ContactError-CONTACT_NOT_FOUND_ERROR'><code>ContactError::CONTACT_NOT_FOUND_ERROR</code></a>.
</p>
@@ -441,7 +442,7 @@
Function to call when the asynchronous operation completes
</dd>
<dt>
- optional ErrorCB errorCB
+ optional ContactErrorCB? errorCB
</dt>
<dd>
Function to call when the asynchronous operation fails.
@@ -453,6 +454,9 @@
<section>
<h2><a>ContactProperties</a> interface</h2>
+ <p class='note'>
+ [PutForwards] are included for information but no group consensus yet on whether it should be included <a href="http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0281.html">[mail]</a>. Do these attributes need to be readonly as defined in the latest <a href="http://www.w3.org/TR/WebIDL/#PutForwards">W3C WebIDL</a> working draft?
+ </p>
<p>
The <a href="#contactproperties-interface"><code>ContactProperties</code></a>
interface captures the settable properties of a contact.
@@ -486,7 +490,7 @@
<pre class="example sh_javascript">{nicknames: ['jim', 'jimmie']}</pre>
</dd>
<dt>
- attribute ContactField[] phones
+ [PutForwards=value] attribute ContactField[] phones
</dt>
<dd>
<p>One or more telephone numbers associated with the contact.</p>
@@ -501,52 +505,49 @@
{types: ['work'], value: '+442088450343'}] }</pre>
</dd>
<dt>
- attribute ContactField[] emails
+ [PutForwards=value] attribute ContactField[] emails
</dt>
<dd>
<p>One or more email addresses associated with the contact.</p>
<p>The first object in this sequence is inferred to be the user's preferred/default email address.</p>
<p>The following constants are defined for use in the <code>types</code> attribute for email addresses:</p>
- <pre>'home', 'work', 'mobile', 'personal', 'business'.</pre>
+ <pre>'home', 'work', 'personal', 'business'.</pre>
<p>Additional values may be provided for the <code>types</code> attribute.</p>
<pre class="example sh_javascript">{emails: [{types: ['work'], value: 'john.q.quinlan@barfooinc.com'},
- {types: ['home'], value: 'jquinlan@mail.com'}]}</pre>
+ {types: ['home', 'mobile'], value: 'jquinlan@mail.com'}]}</pre>
</dd>
<dt>
- attribute ContactField[] addresses
+ [PutForwards=additionalInformation] attribute ContactAddress[] addresses
</dt>
<dd>
<p class='note'>
- May need to align this attribute with ongoing work in the <a href='http://dev.w3.org/geo/api/spec-source-v2.html#address_interface'>Geolocation v2 specification</a>.
- </p>
- <p class='note'>
- Define a ContactAddress interface and break addresses in to individual components?
+ Aligned with <a href='http://dev.w3.org/geo/api/spec-source-v2.html#address_interface'>Geolocation v2 specification</a>.
</p>
<p>One or more addresses associated with the contact.</p>
<p>The first object in this sequence is inferred to be the user's preferred/default address.</p>
-
- <p>The following constants are defined for use in the <code>types</code> attribute for addresses:</p>
- <pre>'home', 'work', 'postal', 'parcel', 'domestic', 'international'.</pre>
- <p>Additional values may be provided for the <code>types</code> attribute.</p>
- <pre class="example sh_javascript">{addresses: [{types: ['domestic','work','postal','parcel'],
- value: '123 Main Street,\nMain Business Park,\nAny Town, CA,\n91921-1234\nUSA'}]}</pre>
+ <pre class="example sh_javascript">{addresses: [{streetNumber: '123',
+ street: 'Main Street',
+ city: 'My Town',
+ region: 'CA',
+ postalCode: '91921-1234',
+ country: 'USA'}]}</pre>
</dd>
<dt>
- attribute ContactField[] impps
+ [PutForwards=value] attribute ContactField[] impps
</dt>
<dd>
<p>One or more instant messaging and presence protocol addresses associated with the contact.</p>
<p>The first object in this sequence is inferred to be the user's preferred/default instant messaging and presence protocol address.</p>
<p>The following constants are defined for use in the <code>types</code> attribute for instant messaging and presence protocol addresses:</p>
- <pre>'home', 'work', 'mobile', 'personal', 'business'.</pre>
+ <pre>'home', 'work', 'personal', 'business'.</pre>
<p>Additional values may be provided for the <code>types</code> attribute.</p>
<pre class="example sh_javascript">{impps: [{types: ['work'], value:'im:jquinlan@foobarinc.com'},
- {types: ['work'], value:'sip:jquinlan@foobarinc.com'}]}</pre>
+ {types: ['work', 'mobile'], value:'sip:jquinlan@foobarinc.com'}]}</pre>
</dd>
<dt>
attribute DOMString? serviceId
@@ -556,7 +557,7 @@
<p>This attribute enables multiple address book sources to be tagged and filtered on Contact objects.</p>
<p>It is recommended that an implementation assign the serviceId attribute as a URI.</p>
- <pre class="example sh_javascript_dom">{serviceId: 'http://foobar.com/calendar'}</pre>
+ <pre class="example sh_javascript_dom">{serviceId: 'http://foobar.com/myservices/v1/addressbook'}</pre>
</dd>
<dt>
attribute DOMString[] categories
@@ -580,7 +581,7 @@
attribute sequence<DOMString>? types
</dt>
<dd>
- One or more contexts to associated with the given <code>value</code>.
+ One or more contexts to associate with the given <code>value</code>.
</dd>
<dt>
attribute DOMString value
@@ -590,22 +591,75 @@
</dd>
</dl>
</section>
-
+
+ <section>
+ <h2><a>ContactAddress</a> interface</h2>
+ <p>
+ The ContactAddress interface is a reusable component that is used to support address information within the <a href='#contactproperties-interface'><code>ContactProperties</code></a> interface.
+ </p>
+ <dl title='[NoInterfaceObject] interface ContactAddress' class='idl'>
+ <dt>
+ attribute DOMString country
+ </dt>
+ <dd>
+ The country of the address, specified using the two-letter [ISO 3166-1] code.
+ </dd>
+ <dt>
+ attribute DOMString region
+ </dt>
+ <dd>
+ The country subdivision (e.g state) of the address.
+ </dd>
+ <dt>
+ attribute DOMString county
+ </dt>
+ <dd>
+ The name of a land area within the larger <a href="#widl-ContactAddress-region"><code>region</code></a>.
+ </dd>
+ <dt>
+ attribute DOMString city
+ </dt>
+ <dd>
+ The city of the address.
+ </dd>
+ <dt>
+ attribute DOMString street
+ </dt>
+ <dd>
+ The street of the address.
+ </dd>
+ <dt>
+ attribute DOMString streetNumber
+ </dt>
+ <dd>
+ The street number of the address.
+ </dd>
+ <dt>
+ attribute DOMString premises
+ </dt>
+ <dd>
+ Details of the premises (e.g. block of flats, building name) of the address.
+ </dd>
+ <dt>
+ attribute DOMString additionalInformation
+ </dt>
+ <dd>
+ Additional information (e.g. floor number in a building, an apartment number, the name of an office occupant, etc) not captured in other <a href="#contactaddress-interface"><code>ContactAddress</code></a> properties.
+ </dd>
+ <dt>
+ attribute DOMString postalCode
+ </dt>
+ <dd>
+ The postal code of the address.
+ </dd>
+ </dl>
+ </section>
+
<section>
<h2><a>ContactOptions</a> interface</h2>
<p class='note'>
Rename this to "ContactSearchFilter" or similar?
</p>
- <p class='note'>
- The options provided in this interface seem to be fairly generic in nature and wondering if we could provide a generic search framework
- that can be used across all APIs (e.g. contacts, calendar, messaging, etc.).
-
- <br /><br />
- Probably yes, but:
- <br />1) it needs to be better specified before we do that, and
- <br />2) we can wait a little before we do some merging. One option to investigate is to look at the multiple existing DB specs that WebApps is progressing, and to use something from there if there happens to be something usable.
- </p>
-
<p>
The <a href='#contactoptions-interface'><code>ContactOptions</code></a>
@@ -639,10 +693,20 @@
</dt>
<dd>
<p class='note'>
+ The ECMA-262 specification says in, section 12.6.4, "[for the for-in Statement t]he mechanics and order of enumerating the
+ properties [...] is not specified."
+ <br /><br />
+ However, all major browsers loop over the properties of an object in the order in which they were defined (ref:
+ <a href="http://stackoverflow.com/questions/648139/is-the-order-of-fields-in-a-javascript-object-predicatble-when-looping-through-th/648163#648163">[1]</a>
+ but independently verified). Chrome has some minor issues, but due to the overwhelming implementation of this behaviour in all other major browsers,
+ the Chrome development team have marked this as a bug and it is due for fix in an upcoming release
+ <a href="http://code.google.com/p/chromium/issues/detail?id=20144">[2]</a>.
+ </p>
+ <p class='note'>
Would it be better to have sort: ['field1', 'field2'] and descending: true|false where the latter is only meaningful if sort was specified?
</p>
<p>
- The way to sort the first enumerable <a href='#contactproperties-interface'><code>ContactProperties</code></a> attribute provided in the related method.
+ The direction in which to sort the first property in the related <a href='#contactproperties-interface'><code>ContactProperties</code></a> object (in the order in which those properties were defined).
</p>
<p>
Only the first <a href='#contactproperties-interface'><code>ContactProperties</code></a> property provided is sortable.
@@ -654,23 +718,26 @@
<p>If a different value is provided, this field defaults to <code>null</code></p>
</dd>
<dt>
- attribute DOMString? group
+ attribute boolean? group
</dt>
<dd>
<p class='note'>
- Perhaps it is not possible to determine what the first enumerable ContactProperties attribute is since it's not ordered??
+ The ECMA-262 specification says in, section 12.6.4, "[for the for-in Statement t]he mechanics and order of enumerating the
+ properties [...] is not specified."
+ <br /><br />
+ However, all major browsers loop over the properties of an object in the order in which they were defined (ref:
+ <a href="http://stackoverflow.com/questions/648139/is-the-order-of-fields-in-a-javascript-object-predicatble-when-looping-through-th/648163#648163">[1]</a>
+ but independently verified). Chrome has some minor issues, but due to the overwhelming implementation of this behaviour in all other major browsers,
+ the Chrome development team have marked this as a bug and it is due for fix in an upcoming release
+ <a href="http://code.google.com/p/chromium/issues/detail?id=20144">[2]</a>.
</p>
<p>
- The way to group the first enumerable <a href='#contactproperties-interface'><code>ContactProperties</code></a> attribute provided in the related method.
+ Whether the first property in the related <a href='#contactproperties-interface'><code>ContactProperties</code></a> object (in the order in which those properties were defined) should be grouped.
</p>
<p>
Only the first <a href='#contactproperties-interface'><code>ContactProperties</code></a> property provided can be grouped.
</p>
- <p>
- This attribute MUST be one of the following constants:
- </p>
- <pre>'asc', 'desc'</pre>
- <p>If a different value is provided, this field defaults to <code>null</code></p>
+
</dd>
</dl>
@@ -723,6 +790,31 @@
</dd>
</dl>
</section>
+
+ <section>
+ <h2><a>ContactErrorCB</a> interface</h2>
+
+ <!-- interface intro here -->
+
+ <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB' class='idl'>
+ <dt>
+ void onError ()
+ </dt>
+ <dd>
+ <!-- interface description here -->
+
+ <dl class='parameters'>
+ <dt>
+ ContactError error
+ </dt>
+ <dd>
+ The Contact API related error object of an unsuccessful asynchronous operation.
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+
+ </section>
<section>
<h2><a>ContactError</a> interface</h2>
@@ -755,31 +847,6 @@
<p class='note'>The following interfaces may be general interfaces for use throughout all APIs. They are included here for now for API spec completion.</p>
- <section>
- <h2><a>ErrorCB</a> interface</h2>
-
- <!-- interface intro here -->
-
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ErrorCB' class='idl'>
- <dt>
- void onError ()
- </dt>
- <dd>
- <!-- interface description here -->
-
- <dl class='parameters'>
- <dt>
- GenericError error
- </dt>
- <dd>
- The error object of an unsuccessful asynchronous operation.
- </dd>
- </dl>
- </dd>
- </dl>
-
- </section>
-
<section>
<h2><a>GenericError</a> interface</h2>
<p>
@@ -825,10 +892,7 @@
<!-- end api description section -->
<section>
<h2><a>Contact Search Processing Rules</a></h2>
- <p class='issue'>
- The algorithm doesn't yet take ContactOptions in to account. This should be added in next update.
- </p>
- <p>
+ <p>
The <a href="#contacts-interface"><code>Contacts</code></a> interface <a href='#widl-Contacts-find'>find()</a> method
provides a method to search for contacts according to the input of a
<a href="#contactproperties-interface"><code>ContactProperties</code></a>
@@ -850,7 +914,7 @@
</p>
<p class='note'>
- We need to be a lot clearer about partial matching included below. It might just be simpler to use pass RegExp objects around. Then again it might not :)
+ We need to be a lot clearer about partial matching included below. It might just be simpler to use pass RegExp objects around. Then again it might not...
</p>
<p>
All contact searching SHOULD apply a loose-matching policy. If a <a href='#contactproperties-interface'><code>ContactProperties</code></a> attribute being searched in <a href='#contacts-interface'><code>Contacts</code></a>
@@ -858,7 +922,7 @@
SHOULD be returned as part of the resulting <a href='#contactfindsuccesscb-interface'><code>ContactFindSuccessCB</code></a>.
</p>
- <p>The <dfn id='rules-for-processing-filter-combinations'>rules for processing filter combinations</dfn> is defined below and is always provided with one <var title="">input</var> parameter. Its behaviour depends on the type of <var title="">input</var>:</p>
+ <p>The <dfn id='rules-for-processing-filter-combinations'>rules for processing filter combinations</dfn> is defined below and is always provided with an <var title="">input</var> parameter and, an optional <var title="">options</var> parameter. Its behaviour depends on the type of <var title="">input</var>:</p>
<dl class='switch'>
@@ -874,6 +938,7 @@
<li>If the value of <var title="">item</var> is <code>null</code>, go to step 2.</li>
<li>Let <var title="">contactsset</var> be the subset of <var title="">contactsset</var> whose elements have the item value set to the value of <var title="">item</var>.</li>
<li>Go to step 2.</li>
+ <li>If the value of <var title="">options</var> is not <code>null</code>. apply the provided <var title="">options</var> to <var title="">contactsset</var>.</li>
<li>Return <var title="">contactsset</var>.</li>
</ol>
</dd>
Received on Thursday, 14 January 2010 17:34:31 UTC