- From: Dominique Hazael-Massieux via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 18 May 2011 14:49:25 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv2618
Modified Files:
Overview.html
Log Message:
simplified search processing as per ACTION-394
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.125
retrieving revision 1.126
diff -u -d -r1.125 -r1.126
--- Overview.html 5 May 2011 16:10:59 -0000 1.125
+++ Overview.html 18 May 2011 14:49:23 -0000 1.126
@@ -764,8 +764,7 @@
<dl title='[NoInterfaceObject] interface ContactFindOptions' class='idl'>
<dt>attribute DOMString? filter</dt>
<dd>
- A string-based <a>search filter</a> with which to search and initially filter the
- <a>Contacts</a> database.
+ A string-based <a>search filter</a> which provides a hint to the user agent to facilitate contacts selection by the user.
</dd>
<dt>attribute boolean? multiple</dt>
<dd>
@@ -1061,207 +1060,18 @@
<h3>Search Filters</h3>
<p>
- A <dfn>search filter</dfn> MAY be specified from a requesting web application to initially filter
- the Contacts database to a more specific set of <a href="#contact-interface"><code>Contact</code></a>
- objects in which it is interested. The <a>search filter</a> is included as the <code>filter</code>
+ A <dfn>search filter</dfn> MAY be specified from a requesting web application to provide a hint to the user agents as to which contacts the user can select to share with the application.</p>
+
+ <p>The <a>search filter</a> is included as the <code>filter</code>
attribute of the <a href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> object
provided to a <a href="#contacts-interface"><code>Contacts</code></a> <a href=
"#widl-Contacts-find">find()</a> operation.
</p>
- <p>
- A <a>search filter</a> is used to search <a href='#contact-interface'><code>Contact</code></a>
- attributes within the <a href="#contacts-interface"><code>Contacts</code></a> database and represents
- the logical union, or <code>∪</code>, of provided values that are matched therein.
- </p>
-
- <p>
- All contact searching MUST apply a <dfn>loose-matching policy</dfn> to the <a>search filter</a>
- provided. If an attribute being searched in a <a href='#contact-interface'><code>Contact</code></a>
- object, stored within the <a href='#contacts-interface'><code>Contacts</code></a> database, is a
- <a>partial value match</a> of the input <code>filter</code> value, that <a href=
- '#contact-interface'><code>Contact</code></a> object MUST be returned as part of the resulting
- <a href='#contactfindcb-interface'><code>ContactFindCB</code></a>.
- </p>
-
- <p>
- A conforming implementation MUST only allow the provided <a>search filter</a> to be applied to
- fields requested in the provided <a>search qualifier</a>. The <code>id</code> attribute MUST always
- be implicitly searchable from any requesting web application regardless of whether it has been
- included as part of any provided <a>search qualifier</a>. For example, if the given <a>search
- qualifier</a> contains 'name' and 'displayName', then the <a>rules for processing search filters</a>
- should only be applied to all sub-fields of the <code>name</code> attribute (i.e.
- <code>name.formatted</code>, <code>name.firstName</code>, <code>name.givenName</code>,
- <code>name.middleName</code>, <code>name.honorificPrefix</code>, <code>name.honorificSuffix</code>),
- the <code>displayName</code> attribute and the <code>id</code> attribute.
- </p>
-
- <p>
- A <dfn>partial value match</dfn> refers to both syntactic and semantic partial matching of an
- input filter value with a corresponding value in the address book and denotes that a corresponding
- match was found in the address book that begins with, contains or ends with the value of the input
- filter value, or any variation thereof.
- </p>
-
- <p>
- Comparing two strings in a <dfn>compatibility caseless</dfn> manner means using the Unicode
- <em>compatibility caseless match</em> operation to compare the two strings. [[!UNICODE]]
- </p>
-
- <p>
- A <a>partial value match</a> MUST use the <a>compatibility caseless</a> manner in which to match
- against corresponding values in the <a href="#contacts-interface"><code>Contacts</code></a>
- database.
- </p>
-
- <p>
-
- </p>
-
- <p>
- The <dfn>rules for processing search filters</dfn> is defined below and is always provided with a
- <var title="filter">filter</var> parameter, representing the <code>filter</code> attribute of the
- <a href="#contactfindoptions-interface"><code>ContactFindOptions</code></a> parameter provided within
- the current <a href="#contacts-interface"><code>Contacts</code></a> <a href=
- "#widl-Contacts-find">find()</a> operation.
- </p>
-
- <dl class='switch'>
- <dt> </dt>
-
- <dd>
- Let <var title="contactsets">contactsets</var> be initially the set of all known contacts in the
- <a href="#contacts-interface"><code>Contacts</code></a> database.
-
- <p>
- Let <var title="contactsresult">contactsresult</var> be initially an empty Array object.
- </p>
- </dd>
-
- <dt>If <var title="filter">filter</var> is a DOMString object</dt>
-
- <dd>
- <ol class="rule">
- <li>Let <var title="contactset">contactset</var> be the next enumerable Object in <var title=
- "contactsets">contactsets</var>. If there is no next enumerable Object, go to step 5.</li>
-
- <li>Let <var title="partialMatchFound">partialMatchFound</var> be the result of applying the
- <a>partial matching algorithm</a>, providing <var title="filter">filter</var> and <var title=
- "contactset">contactset</var> as inputs.</li>
-
- <li>If <var title="partialMatchFound">partialMatchFound</var> is <code>true</code>, add
- <var title="contactset">contactset</var> to <var title=
- "contactsresult">contactsresult</var>.</li>
-
- <li>Go to step 1.</li>
-
- <li>Return <var title="contactsresult">contactsresult</var>.</li>
- </ol>
- </dd>
-
- <dt>If <var title="filter">filter</var> is another native object type</dt>
-
- <dd>
- <p>
- Return <var title="contactsets">contactsets</var>.
- </p>
- </dd>
- </dl>
-
- <p>
-
- </p>
-
- <p>
- The <dfn>partial matching algorithm</dfn> is defined below and is always provided with a
- <var title="filter">filter</var> parameter, representing the input string to compare; and a
- <var title="contactset">contactset</var> parameter, representing an individual <a href=
- "#contact-interface"><code>Contact</code></a> object:
+ <p>The actual usage of this <a>search filter</a> is user-agent dependant, but is expected to represent
+ the logical union of provided values that are matched therein.
</p>
-
- <dl class='switch'>
- <dt> </dt>
-
- <dd>Let <var title="hasPartialMatch">hasPartialMatch</var> be initially set to
- <code>false</code>.</dd>
-
- <dt>If <var title="contactset">contactset</var> is an Object object</dt>
-
- <dd>
- <ol class="rule">
- <li>Let <var title="elementvalue">elementvalue</var> be the String value of the next enumerable
- property in <var title="contactset">contactset</var>. If there are no more enumerable
- properties, go to step 5.</li>
-
- <li>Let <var title="hasPartialMatch">hasPartialMatch</var> be the boolean result for the
- comparison of <var title="filter">filter</var> with <var title=
- "elementvalue">elementvalue</var> in a <a>compatibility caseless</a> manner and with a
- <a>partial value match</a> policy applied to both sides of the comparison operation.</li>
-
- <li>If <var title="hasPartialMatch">hasPartialMatch</var> is <code>true</code>, go to step
- 5.</li>
-
- <li>Go to step 1.</li>
-
- <li>Return <var title="hasPartialMatch">hasPartialMatch</var>.</li>
- </ol>
- </dd>
-
- <dt>If <var title="contactset">contactset</var> is another native object type</dt>
-
- <dd>
- <p>
- Return <code>false</code>.
- </p>
- </dd>
- </dl>
-
- <div class="example">
- <p>
- The following Contact search is initiated:
- </p>
- <pre class="sh_javascript">
- navigator.contacts( ['name', 'addresses.locality', 'addresses.country', 'phoneNumbers', 'emails'],
- function(contacts) {
- for(x in contacts) alert(contacts[x].name);
- },
- { filter: 'Robert' } );
-
- </pre>
-
- <p>
- The above example logically implies:
- </p>
-
- <ol class="rule">
- <li>Using ECMA-262 3rd Edition regular expression syntax and pseudo-code, the <a>search
- filter</a> provided can be represented as:
- <pre>
- ( name.formatted = /∧.*Robert.*$/i ) ∪ ( phoneNumbers.value = /∧.*Robert.*$/i )
- ∪ ( emails.value = /∧.*Robert.*$/i ) ∪ ( name.familyName = /∧.*Robert.*$/i )
- ∪ ( name.givenName = /∧.*Robert.*$/i ) ∪ ( name.middleName = /∧.*Robert.*$/i )
- ∪ ( addresses.country = /∧.*Robert.*$/i ) ∪ ( addresses.locality = /∧.*Robert.*$/i )
- ∪ ( phoneNumbers.type = /∧.*Robert.*$/i ) ∪ ( emails.type = /∧.*Robert.*$/i )
- ∪ ( id = /∧.*Robert.*$/i )
- </pre><br>
- All searches are case-insensitive and apply a <a>loose-matching policy</a> as defined in
- <a href="#search-filters">Search Filters</a>.<br>
- <br>
- As noted in <a href="#search-filters">Search Filters</a>, the <code>id</code> attribute is
- implicitly appended along with any <a>search filter</a> attributes provided, regardless of
- whether it was provided as a <a>search qualifier</a> from the requesting application.<br>
- <br>
- </li>
-
- <li>Return only the valid <a href="#contact-interface"><code>Contact</code></a> properties
- requested in the provided <a>search qualifier</a> (<code>name</code>,
- <code>addresses.locality</code>, <code>addresses.country</code>, <code>phoneNumbers</code>,
- <code>emails</code>) and only for the <a href="#contact-interface"><code>Contact</code></a>
- objects returned from the <a>rules for processing search filters</a> with the <a>search
- filter</a> derived in step 1 provided as the <var>filter</var> input parameter.</li>
- </ol>
- </div>
- </section>
+ </section>
</section>
</section>
Received on Wednesday, 18 May 2011 14:49:57 UTC