W3C home > Mailing lists > Public > public-dap-commits@w3.org > December 2009

2009/dap/contacts Overview.html,1.16,1.17

From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
Date: Fri, 11 Dec 2009 15:21:38 +0000
To: public-dap-commits@w3.org
Message-Id: <E1NJ7JK-0003o5-MO@lionel-hutz.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&lt;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>&quot;find contact objects that contain a name of 'Robert' AND a nickname of 'Bob'&quot;</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>&quot;find contact objects that contain a name of 'Robert' OR a nickname of 'Bob'&quot;</em>.
-				
-				</p>
-				
-				<p>&nbsp;</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 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Friday, 11 December 2009 15:21:47 GMT