- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 11 Dec 2009 15:21:38 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv14605
Modified Files:
Overview.html
Log Message:
Updates:
- Added initial sorting and grouping to the ContactOptions interface.
- Removed Contacts.find() overloading due to addition of sorting and grouping functionality and on the groups that OR functionality can be adequately acheived via multiple find() requests.
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- Overview.html 11 Dec 2009 15:14:45 -0000 1.16
+++ Overview.html 11 Dec 2009 15:21:36 -0000 1.17
@@ -338,51 +338,6 @@
</dd>
</dl>
</dd>
- <dt>
- PendingOp find ()
- </dt>
- <dd>
- <p>Find contacts in the address book based on a sequence of <a href='#contactproperties-typedef'><code>ContactProperties</code></a> objects acting as filters.</p>
-
- <p>This method takes two, three or four arguments. When called, it must immediately return
- a <code>PendingOp</code> object , as defined in [[CORE-DEVICE]], and then asynchronously start a <dfn>find contacts process</dfn> defined as follows:</p>
-
- <p>
- <ol>
- <li>Search for contacts in the address book according to the <a href='#contact-search-processing-rules'>contact search processing rules</a>.</li>
- <li>If successful, invoke the associated <code>successCB</code>.
- If the attempt fails, and the method was invoked with a non-null <code>errorCB</code> argument, this method must
- invoke the <code>errorCB</code> with a <a href='#contacterror-interface'><code>ContactError</code></a> object as an argument.</li>
- </ol>
- </p>
-
- <dl class='parameters'>
- <dt>
- sequence<ContactProperties> filters
- </dt>
- <dd>
- The filters used in order to select which contacts are returned.
- </dd>
- <dt>
- ContactFindSuccessCB successCB
- </dt>
- <dd>
- Function to call when the asynchronous operation completes
- </dd>
- <dt>
- optional ErrorCB errorCB
- </dt>
- <dd>
- Function to call when the asynchronous operation fails. This parameter is OPTIONAL.
- </dd>
- <dt>
- optional ContactOptions options
- </dt>
- <dd>
- The options to apply to the output of this method. This parameter is OPTIONAL.
- </dd>
- </dl>
- </dd>
</dl>
</section>
@@ -675,6 +630,38 @@
DEFAULT = 1
</p>
</dd>
+ <dt>
+ attribute DOMString? sort
+ </dt>
+ <dd>
+ <p>
+ The way to sort the first enumerable <a href='#contactproperties-interface'><code>ContactProperties</code></a> attribute provided in the related method.
+ </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 constant is provided, this field defaults to <code>NULL</code></p>
+ </dd>
+ <dt>
+ attribute DOMString? group
+ </dt>
+ <dd>
+ <p>
+ The way to group the first enumerable <a href='#contactproperties-interface'><code>ContactProperties</code></a> attribute provided in the related method.
+ </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 constant is provided, this field defaults to <code>NULL</code></p>
+ </dd>
</dl>
</section>
@@ -848,17 +835,15 @@
<h2><a>Contact Search processing rules</a></h2>
<p>
The <a href="#contacts-interface"><code>Contacts</code></a> interface <a href='#widl-Contacts-find'>find()</a> method
- allows <var title=''>filter</var>
- overloading to search for contacts according to the input of a single
- <a href="#contactproperties-interface"><code>ContactProperties</code></a>
- object or a sequence of
+ provides a method to search for contacts according to the input of a
<a href="#contactproperties-interface"><code>ContactProperties</code></a>
- objects.
+ object.
<p>
- All fields within a single <a href="#contactproperties-interface"><code>ContactProperties</code></a> object represent a logical UNION of value matching. All fields between a set of <a href="#contactproperties-interface"><code>ContactProperties</code></a> objects represent a logical JOIN of value matching.
+ All fields within a <a href="#contactproperties-interface"><code>ContactProperties</code></a> object provided to this method represent a logical UNION of value matching.
+ Fields provided with a <code>NULL</code> value are considered to match anything.
</p>
<p>
- For a single ContactProperties object supplied for Contact searching:
+ For example, the following <a href="#contactproperties-interface"><code>ContactProperties</code></a> object is supplied for Contact searching:
<pre class="example sh_javascript">navigator.contacts.find({
name:'Robert',
nicknames:['Bob']
@@ -867,22 +852,7 @@
The above example logically implies: <em>"find contact objects that contain a name of 'Robert' AND a nickname of 'Bob'"</em>.
</p>
- <p>
- For multiple ContactProperties objects supplied for Contact searching:
- <pre class="example sh_javascript">navigator.contacts.find([{
- name:'Robert'
- },
- {
- nicknames:['Bob']
- }],
- /*...*/);</pre>
-
- The above example logically implies: <em>"find contact objects that contain a name of 'Robert' OR a nickname of 'Bob'"</em>.
-
- </p>
-
- <p> </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>
<dl class=switch>
@@ -890,20 +860,6 @@
<dt></dt>
<dd>Let <var title="">contactsset</var> be initially the set of all known contacts</dd>
- <dt>If <var title="">input</var> is an Array object</dt>
-
- <dd>
- <ol>
- <li>Let <var title="">multiplefilters</var> be the <var title="">input</var> parameter being parsed.</li>
- <li>Let <var title="">singlefilter</var> be the next index in <var title="">mutiplefilters</var>. If there are no more indices, go to step 6.</li>
- <li>Let <var title="">filteredcontactset</var> be the result of processing <var title="">contactsset</var> with <var title="">singlefilter</var> through the <a href="#rules-for-processing-filter-combinations">rules for processing filter combinations</a>.</li>
- <li>Let <var title="">contactsset</var> be the union of <var title="">contactsset</var> with <var title="">filteredcontactsset</var>.</li>
- <li>Go to step 2.</li>
- <li>Return <var title="">contactsset</var>.</li>
- </ol>
-
- </dd>
-
<dt>If <var title="">input</var> is an Object object</dt>
<dd>
Received on Friday, 11 December 2009 15:21:47 UTC