- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 24 Feb 2010 11:36:45 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv26326
Modified Files:
Overview.html
Log Message:
- Initial changes to Contacts.find() and ContactOptions according to mailing list discussion: http://lists.w3.org/Archives/Public/public-device-apis/2010Feb/0109.html (full thread)
- ContactOptions renamed to ContactFindOptions
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -d -r1.45 -r1.46
--- Overview.html 18 Feb 2010 18:28:58 -0000 1.45
+++ Overview.html 24 Feb 2010 11:36:43 -0000 1.46
@@ -18,6 +18,7 @@
</script>
<script src='../common/config.js' class='remove'>
</script>
+ <link rel="stylesheet" href="../ReSpec.js/css/respec.css" type="text/css" media="screen" />
</head>
<body>
<section id='abstract'>
@@ -71,9 +72,12 @@
}
// Perform an address book search
-navigator.service.contacts.find( {name: 'Bob'},
+navigator.service.contacts.find( ['name', 'emails'],
successContactFindCallback,
- generalErrorCB );</pre>
+ generalErrorCB,
+ {filter:
+ {'name': 'Bob'}
+ } );</pre>
</div>
<div>
<p>
@@ -135,16 +139,6 @@
<p class='note'>
<strong>This section is under development.</strong>
-
- <br /><br />This section has been inspired (verbatim where necessary) from the <a href='http://www.w3.org/2008/geolocation/'>Geolocation WG</a> <a href='http://www.w3.org/TR/2009/WD-geolocation-API-20090707/'>latest public working draft specification</a>.
-
- <br /><br />There are a number of reasons for this approach:
-
- <br /><br />1. The programmatic styles of the Contacts API and Geolocation API are very similar and because they both have the the same implied user experience within
- the same implied User Agent the general security and privacy considerations of both APIs should remain common.
-
- <br /><br />2. The ability to align the security and privacy considerations of the Geolocation API with DAP APIs is important for the potential future benefit
- of making any security and privacy mechanisms developed within the DAP WG applicable to the Geolocation API at some point in its own ongoing development.
</p>
<p>
@@ -312,10 +306,15 @@
<dl class='parameters'>
<dt>
- ContactProperties filter
+ DOMString[] fields
</dt>
<dd>
- The filter used in order to select which contacts are returned.
+ A DOMString-based list of <a href='#contactproperties-interface'><code>ContactProperties</code></a> fields that are
+ requested to be returned as part of the associated <a href='#contactfindsuccesscb-interface'><code>ContactFindSuccessCB</code></a>.
+
+ <p>
+ This method returns no ContactProperties by default. Therefore the requested <a href='#contact-interface'><code>Contact</code></a> fields MUST be specified as part of this operation.
+ </p>
</dd>
<dt>
ContactFindSuccessCB successCB
@@ -330,7 +329,7 @@
Function to call when the asynchronous operation fails.
</dd>
<dt>
- optional ContactOptions options
+ optional ContactFindOptions options
</dt>
<dd>
The options to apply to the output of this method.
@@ -617,9 +616,6 @@
<section>
<h2><a>Address</a> interface</h2>
- <p class='note'>
- Aligned with <a href='http://dev.w3.org/geo/api/spec-source-v2.html#address_interface'>Geolocation v2 specification</a>.
- </p>
<p>
The Address interface supports address information for use in the <a href='#contactaddress-interface'><code>ContactAddress</code></a> interface.
</p>
@@ -682,16 +678,24 @@
</section>
<section>
- <h2><a>ContactOptions</a> interface</h2>
- <p class='note'>
- Rename this to "ContactSearchFilter" or similar?
- </p>
-
+ <h2><a>ContactFindOptions</a> interface</h2>
<p>
- The <a href='#contactoptions-interface'><code>ContactOptions</code></a>
+ The <a href='#contactfindoptions-interface'><code>ContactFindOptions</code></a>
interface describes the options that can be applied to contact searching.
</p>
- <dl title='[NoInterfaceObject] interface ContactOptions' class='idl'>
+ <dl title='[NoInterfaceObject] interface ContactFindOptions' class='idl'>
+ <dt>
+ attribute ContactProperties? filter
+ </dt>
+ <dd>
+ An optional set of <a href='#contactproperties-interface'><code>ContactProperties</code></a> to initially filter in the <a>contacts picker</a>.
+ </dd>
+ <dt>
+ attribute boolean? multiple
+ </dt>
+ <dd>
+ A boolean value to indicate whether multiple Contact objects are returnable as part of the associated <a href='#widl-Contacts-find'><code>Contacts.find()</code></a> method.
+ </dd>
<dt>
attribute unsigned short limit
</dt>
@@ -700,72 +704,12 @@
The maximum number of results to return from the contacts search.
</p>
<p>
- If no value is provided, the search will return all search results.
- </p>
- </dd>
- <dt>
- attribute unsigned short page
- </dt>
- <dd>
- <p>
- The page number of the contacts search to return. If the requested page index does not exist, this parameter MUST be assigned the default value.
- </p>
- <p>
- If no value is provided, the search will return all search results.
- </p>
- </dd>
- <dt>
- attribute DOMString? sort
- </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://ejohn.org/blog/javascript-in-chrome/"><cite>JavaScript in Chrome</cite> blog post</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 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).
+ This parameter only applies in the case that the associated multiple attribute is equal to <code>true</code>.
</p>
<p>
- Only the first <a href='#contactproperties-interface'><code>ContactProperties</code></a> property provided is sortable.
- </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>
- <dt>
- attribute boolean? group
- </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://ejohn.org/blog/javascript-in-chrome/"><cite>JavaScript in Chrome</cite> blog post</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>
- 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.
+ If no value is provided, the search will return all <a href='#contact-interface'><code>Contact</code></a> object results.
</p>
- <p>
- Only the first <a href='#contactproperties-interface'><code>ContactProperties</code></a> property provided can be grouped.
- </p>
-
- </dd>
-
+ </dd>
</dl>
</section>
@@ -871,8 +815,6 @@
This section defines the general API interfaces required by this specification that MAY also be in use in other DAP APIs.
- <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>GenericError</a> interface</h2>
<p>
@@ -929,14 +871,26 @@
Fields provided with a <code>null</code> value are considered to match anything.
</p>
<p>
- For example, the following <a href="#contactproperties-interface"><code>ContactProperties</code></a> object is supplied for Contact searching:
- <pre class="example sh_javascript">navigator.service.contacts.find({
- name:'Robert',
- nicknames:['Bob']
- },
- /*...*/);</pre>
+ For example, the following Contact search is initiated:
+ <pre class="example sh_javascript">// Perform an address book search
+navigator.service.contacts.find(
+ ['name', 'addresses', 'phones', 'emails'],
+ successContactFindCallback,
+ generalErrorCB,
+ {
+ 'filter':
+ {
+ 'name': 'Robert',
+ 'nicknames': 'Bob'
+ },
+ 'multiple': true,
+ 'limit': 3
+ }
+ );</pre>
- The above example logically implies: <em>"find contact objects that contain a name of 'Robert' AND a nickname of 'Bob'"</em>.
+ The above example logically implies: <pre>1. Initally filter the contacts picker to Contact objects that contain a name of 'Robert' AND a nickname of 'Bob'.
+
+2. Return the 'name', 'addresses', 'phones' and 'emails' attributes of the resulting Contact objects.</pre>
</p>
<p class='note'>
Received on Wednesday, 24 February 2010 11:36:47 UTC