Add suggestions parameter.
authorGreg Billock <gbillock@google.com>
Wed, 16 May 2012 11:51:17 -0700
changeset 13 4fa8625abf77
parent 12 cfbd8857aa0f
child 14 1b7596aacd4c
Add suggestions parameter.
spec/Overview-respec.html
spec/Overview.html
--- a/spec/Overview-respec.html	Fri Apr 27 13:13:04 2012 -0700
+++ b/spec/Overview-respec.html	Wed May 16 11:51:17 2012 -0700
@@ -310,6 +310,9 @@
         <dt>readonly attribute URL service</dt>
         <dd>When present, this field marks the intent as an explicit intent. The
         value MUST be an absolute URL.</dd>
+        <dt>readonly attribute sequence&lt;URL&gt; suggestions</dt>
+        <dd>When present, this field provides a list of (absolute) suggested Service URLs
+        of which the Client is aware and which can handle the intent.</dd>
       </dl>
     </section>
     <section>
@@ -729,7 +732,7 @@
       </section>
 
       <section>
-      <h3>Matching action and types for delivery</h3>
+      <h3>Matching action and type for delivery</h3>
       <p>
       When an Intent is delivered, the User Agent must verify that the Service to
       which the intent is to be delivered (either from an explicit invocation or from
@@ -780,6 +783,32 @@
       </ol>
       </section>
 
+      <section>
+      <h3>Handling Service suggestions from Intent Invocation</h3>
+      <p>
+      If the user has no persistent information about a qualifying service
+      for a particular intent registered with the User Agent, the User Agent
+      SHOULD present the user with the option to select from the default
+      services proposed by the client at invocation (from the <i>suggestions</i>
+      parameter).
+      </p>
+      <p>
+      If the user agent needs information about the all or any of the
+      suggested services (i.e. disposition, title, icon, etc) for use in
+      preparing its UI, it MAY load the suggested default service URL(s) and
+      examine the page(s) for the &lt;intent&gt; tag, reading off such information,
+      or load the favicon for the site(s). The User Agent SHOULD ignore the
+      suggested services from the intent invocation if the user already has a handler
+      selected. The User Agent MAY ask the user if they wish to install all
+      or any of the suggested services, just as for any other visit of those pages.
+      </p>
+      <p>
+      The User Agent MUST follow the matching algorithm of the "Matching action
+      and type for delivery" section before delivering
+      the Intent to a suggested service, just as for any Intent delivery.
+      </p>
+      </section>
+
     </section>
 
     <section>
--- a/spec/Overview.html	Fri Apr 27 13:13:04 2012 -0700
+++ b/spec/Overview.html	Wed May 16 11:51:17 2012 -0700
@@ -477,7 +477,7 @@
 pre.sh_sourceCode .sh_attribute { color: #006400; }
 
 </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css" charset="utf-8"></head>
-  <body style="display: inherit; "><div class="head"><p><a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a></p><h1 class="title" id="title">Web Intents</h1><h2 id="w3c-editor-s-draft-27-april-2012"><acronym title="World Wide Web Consortium">W3C</acronym> Editor's Draft 27 April 2012</h2><dl><dt>This version:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/web-intents/">http://www.w3.org/TR/web-intents/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Previous version:</dt><dd>none</dd><dt>Editors:</dt><dd><span>Greg Billock</span>, <a href="http://google.com/">Google</a></dd>
+  <body style="display: inherit; "><div class="head"><p><a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a></p><h1 class="title" id="title">Web Intents</h1><h2 id="w3c-editor-s-draft-16-may-2012"><acronym title="World Wide Web Consortium">W3C</acronym> Editor's Draft 16 May 2012</h2><dl><dt>This version:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/web-intents/">http://www.w3.org/TR/web-intents/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2011/webapps/TODO.html">http://dev.w3.org/2011/webapps/TODO.html</a></dd><dt>Previous version:</dt><dd>none</dd><dt>Editors:</dt><dd><span>Greg Billock</span>, <a href="http://google.com/">Google</a></dd>
 <dd><span>James Hawkins</span>, <a href="http://google.com/">Google</a></dd>
 <dd><span>Paul Kinlan</span>, <a href="http://google.com/">Google</a></dd>
 </dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2012 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. <acronym title="World Wide Web Consortium">W3C</acronym> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p><hr></div>
@@ -491,7 +491,7 @@
       pages to create, receive, and reply to Web Intents messages, and the
       procedures the User Agent carries out to facilitate that process.
       </p>
-    </div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <acronym title="World Wide Web Consortium">W3C</acronym> publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide Web Consortium">W3C</acronym> technical reports index</a> at http://www.w3.org/TR/.</em></p><p>This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications (WebApps) Working Group</a> as an Editor's Draft. If you wish to make comments regarding this document, please send them to <a href="mailto:public-web-intents@w3.org">public-web-intents@w3.org</a> (<a href="mailto:public-web-intents-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-web-intents/">archives</a>). All feedback is welcome.</p><p>Publication as an Editor's Draft does not imply endorsement by the <acronym title="World Wide Web Consortium">W3C</acronym> Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>. <acronym title="World Wide Web Consortium">W3C</acronym> maintains a <a href="TODO" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>.</p></div><div id="toc" class="section"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#example" class="tocxref"><span class="secno">1.1 </span>Example</a></li><li class="tocline"><a href="#normative-parts" class="tocxref"><span class="secno">1.2 </span>Normative parts</a></li></ul></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">2. </span>Terminology</a><ul class="toc"><li class="tocline"><a href="#actors" class="tocxref"><span class="secno">2.1 </span>Actors</a></li><li class="tocline"><a href="#life-cycle-of-intents" class="tocxref"><span class="secno">2.2 </span>Life cycle of Intents</a></li></ul></li><li class="tocline"><a href="#api-description" class="tocxref"><span class="secno">3. </span>API Description</a><ul class="toc"><li class="tocline"><a href="#intent-parameters-dictionary" class="tocxref"><span class="secno">3.1 </span>Intent parameters dictionary</a><ul class="toc"><li class="tocline"><a href="#dictionary-intentparameters-members" class="tocxref"><span class="secno">3.1.1 </span>Dictionary <span class="idlType formerLink idlType"><code>IntentParameters</code></span> Members</a></li></ul></li><li class="tocline"><a href="#intent-object" class="tocxref"><span class="secno">3.2 </span>Intent object</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">3.2.1 </span>Attributes</a></li><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">3.2.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#invocation-api" class="tocxref"><span class="secno">3.3 </span>Invocation API</a><ul class="toc"><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">3.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#delivery-and-response-api" class="tocxref"><span class="secno">3.4 </span>Delivery and Response API</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">3.4.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#registration-markup" class="tocxref"><span class="secno">3.5 </span>Registration Markup</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">3.5.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a href="#user-agent-behavior" class="tocxref"><span class="secno">4. </span>User Agent Behavior</a><ul class="toc"><li class="tocline"><a href="#explicit-intents" class="tocxref"><span class="secno">4.1 </span>Explicit Intents</a></li><li class="tocline"><a href="#matching-action-and-types-for-delivery" class="tocxref"><span class="secno">4.2 </span>Matching action and types for delivery</a></li></ul></li><li class="tocline"><a href="#use-cases-and-requirements" class="tocxref"><span class="secno">5. </span>Use Cases and Requirements</a><ul class="toc"><li class="tocline"><a href="#sharing" class="tocxref"><span class="secno">5.1 </span>Sharing</a></li><li class="tocline"><a href="#integration-with-local-web-apps" class="tocxref"><span class="secno">5.2 </span>Integration with local web apps</a></li><li class="tocline"><a href="#persistent-connections" class="tocxref"><span class="secno">5.3 </span>Persistent connections</a></li><li class="tocline"><a href="#integration-with-external-applications" class="tocxref"><span class="secno">5.4 </span>Integration with external applications</a></li><li class="tocline"><a href="#translating-existing-web-platform-features-to-intents" class="tocxref"><span class="secno">5.5 </span>Translating existing web platform features to intents</a></li><li class="tocline"><a href="#authentication" class="tocxref"><span class="secno">5.6 </span>Authentication</a></li></ul></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
+    </div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <acronym title="World Wide Web Consortium">W3C</acronym> publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide Web Consortium">W3C</acronym> technical reports index</a> at http://www.w3.org/TR/.</em></p><p>This document was published by the <a href="http://www.w3.org/2008/webapps/">Web Applications (WebApps) Working Group</a> as an Editor's Draft. If you wish to make comments regarding this document, please send them to <a href="mailto:public-web-intents@w3.org">public-web-intents@w3.org</a> (<a href="mailto:public-web-intents-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-web-intents/">archives</a>). All feedback is welcome.</p><p>Publication as an Editor's Draft does not imply endorsement by the <acronym title="World Wide Web Consortium">W3C</acronym> Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>. <acronym title="World Wide Web Consortium">W3C</acronym> maintains a <a href="TODO" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>.</p></div><div id="toc" class="section"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#example" class="tocxref"><span class="secno">1.1 </span>Example</a></li><li class="tocline"><a href="#normative-parts" class="tocxref"><span class="secno">1.2 </span>Normative parts</a></li></ul></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">2. </span>Terminology</a><ul class="toc"><li class="tocline"><a href="#actors" class="tocxref"><span class="secno">2.1 </span>Actors</a></li><li class="tocline"><a href="#life-cycle-of-intents" class="tocxref"><span class="secno">2.2 </span>Life cycle of Intents</a></li></ul></li><li class="tocline"><a href="#api-description" class="tocxref"><span class="secno">3. </span>API Description</a><ul class="toc"><li class="tocline"><a href="#intent-parameters-dictionary" class="tocxref"><span class="secno">3.1 </span>Intent parameters dictionary</a><ul class="toc"><li class="tocline"><a href="#dictionary-intentparameters-members" class="tocxref"><span class="secno">3.1.1 </span>Dictionary <span class="idlType formerLink idlType"><code>IntentParameters</code></span> Members</a></li></ul></li><li class="tocline"><a href="#intent-object" class="tocxref"><span class="secno">3.2 </span>Intent object</a><ul class="toc"><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">3.2.1 </span>Attributes</a></li><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">3.2.2 </span>Methods</a></li></ul></li><li class="tocline"><a href="#invocation-api" class="tocxref"><span class="secno">3.3 </span>Invocation API</a><ul class="toc"><li class="tocline"><a href="#methods-1" class="tocxref"><span class="secno">3.3.1 </span>Methods</a></li></ul></li><li class="tocline"><a href="#delivery-and-response-api" class="tocxref"><span class="secno">3.4 </span>Delivery and Response API</a><ul class="toc"><li class="tocline"><a href="#attributes-1" class="tocxref"><span class="secno">3.4.1 </span>Attributes</a></li></ul></li><li class="tocline"><a href="#registration-markup" class="tocxref"><span class="secno">3.5 </span>Registration Markup</a><ul class="toc"><li class="tocline"><a href="#attributes-2" class="tocxref"><span class="secno">3.5.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a href="#user-agent-behavior" class="tocxref"><span class="secno">4. </span>User Agent Behavior</a><ul class="toc"><li class="tocline"><a href="#explicit-intents" class="tocxref"><span class="secno">4.1 </span>Explicit Intents</a></li><li class="tocline"><a href="#matching-action-and-type-for-delivery" class="tocxref"><span class="secno">4.2 </span>Matching action and type for delivery</a></li><li class="tocline"><a href="#handling-service-suggestions-from-intent-invocation" class="tocxref"><span class="secno">4.3 </span>Handling Service suggestions from Intent Invocation</a></li></ul></li><li class="tocline"><a href="#use-cases-and-requirements" class="tocxref"><span class="secno">5. </span>Use Cases and Requirements</a><ul class="toc"><li class="tocline"><a href="#sharing" class="tocxref"><span class="secno">5.1 </span>Sharing</a></li><li class="tocline"><a href="#integration-with-local-web-apps" class="tocxref"><span class="secno">5.2 </span>Integration with local web apps</a></li><li class="tocline"><a href="#persistent-connections" class="tocxref"><span class="secno">5.3 </span>Persistent connections</a></li><li class="tocline"><a href="#integration-with-external-applications" class="tocxref"><span class="secno">5.4 </span>Integration with external applications</a></li><li class="tocline"><a href="#translating-existing-web-platform-features-to-intents" class="tocxref"><span class="secno">5.5 </span>Translating existing web platform features to intents</a></li><li class="tocline"><a href="#authentication" class="tocxref"><span class="secno">5.6 </span>Authentication</a></li></ul></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a href="#informative-references" class="tocxref"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
     
     <div id="introduction" class="section">
       <!--OddPage--><h2><span class="secno">1. </span>Introduction</h2>
@@ -691,11 +691,13 @@
 <span class="idlMember">    <span class="idlMemberType"><a>readonly attribute sequence<transferable></transferable></a></span> <span class="idlMemberName"><a href="#widl-IntentParameters-transfer">transfer</a></span>;</span>
 <span class="idlMember">    <span class="idlMemberType"><a>readonly attribute dictionary<string></string></a></span>     <span class="idlMemberName"><a href="#widl-IntentParameters-extras">extras</a></span>;</span>
 <span class="idlMember">    <span class="idlMemberType"><a>readonly attribute URL</a></span>                    <span class="idlMemberName"><a href="#widl-IntentParameters-service">service</a></span>;</span>
+<span class="idlMember">    <span class="idlMemberType"><a>readonly attribute sequence<url></url></a></span>          <span class="idlMemberName"><a href="#widl-IntentParameters-suggestions">suggestions</a></span>;</span>
 };</span>
 </pre><div id="dictionary-intentparameters-members" class="section"><h4><span class="secno">3.1.1 </span>Dictionary <a class="idlType" href="#idl-def-IntentParameters"><code>IntentParameters</code></a> Members</h4><dl class="dictionary-members"><dt id="widl-IntentParameters-action"><code>action</code> of type <span class="idlMemberType"><a>readonly attribute DOMString</a></span></dt><dd>An opaque string indicating the action type of the intent. The
         string <em class="rfc2119" title="must not">must not</em> be empty.</dd><dt id="widl-IntentParameters-data"><code>data</code> of type <span class="idlMemberType"><a>readonly attribute any</a></span></dt><dd>The data payload used <em class="rfc2119" title="must">must</em> be an object upon which the structured
         clone algorithm can be performed, including Transferables.</dd><dt id="widl-IntentParameters-extras"><code>extras</code> of type <span class="idlMemberType"><a>readonly attribute dictionary&lt;string&gt;</a></span></dt><dd>A key-value map of extra metadata to be sent with the intent.</dd><dt id="widl-IntentParameters-service"><code>service</code> of type <span class="idlMemberType"><a>readonly attribute URL</a></span></dt><dd>When present, this field marks the intent as an explicit intent. The
-        value <em class="rfc2119" title="must">must</em> be an absolute URL.</dd><dt id="widl-IntentParameters-transfer"><code>transfer</code> of type <span class="idlMemberType"><a>readonly attribute sequence&lt;Transferable&gt;</a></span></dt><dd>The list of Transferables, for use in the structured clone
+        value <em class="rfc2119" title="must">must</em> be an absolute URL.</dd><dt id="widl-IntentParameters-suggestions"><code>suggestions</code> of type <span class="idlMemberType"><a>readonly attribute sequence&lt;URL&gt;</a></span></dt><dd>When present, this field provides a list of (absolute) suggested Service URLs
+        of which the Client is aware and which can handle the intent.</dd><dt id="widl-IntentParameters-transfer"><code>transfer</code> of type <span class="idlMemberType"><a>readonly attribute sequence&lt;Transferable&gt;</a></span></dt><dd>The list of Transferables, for use in the structured clone
         algorithm.</dd><dt id="widl-IntentParameters-type"><code>type</code> of type <span class="idlMemberType"><a>readonly attribute DOMString</a></span></dt><dd>A string indicating the type of the data payload. The data payload
         <em class="rfc2119" title="must">must</em> be described by this parameter, which <em class="rfc2119" title="must not">must not</em> be empty.</dd></dl></div>
     </div>
@@ -1109,8 +1111,8 @@
       </p>
       </div>
 
-      <div id="matching-action-and-types-for-delivery" class="section">
-      <h3><span class="secno">4.2 </span>Matching action and types for delivery</h3>
+      <div id="matching-action-and-type-for-delivery" class="section">
+      <h3><span class="secno">4.2 </span>Matching action and type for delivery</h3>
       <p>
       When an Intent is delivered, the User Agent must verify that the Service to
       which the intent is to be delivered (either from an explicit invocation or from
@@ -1161,6 +1163,32 @@
       </ol>
       </div>
 
+      <div id="handling-service-suggestions-from-intent-invocation" class="section">
+      <h3><span class="secno">4.3 </span>Handling Service suggestions from Intent Invocation</h3>
+      <p>
+      If the user has no persistent information about a qualifying service
+      for a particular intent registered with the User Agent, the User Agent
+      <em class="rfc2119" title="should">should</em> present the user with the option to select from the default
+      services proposed by the client at invocation (from the <i>suggestions</i>
+      parameter).
+      </p>
+      <p>
+      If the user agent needs information about the all or any of the
+      suggested services (i.e. disposition, title, icon, etc) for use in
+      preparing its UI, it <em class="rfc2119" title="may">may</em> load the suggested default service URL(s) and
+      examine the page(s) for the &lt;intent&gt; tag, reading off such information,
+      or load the favicon for the site(s). The User Agent <em class="rfc2119" title="should">should</em> ignore the
+      suggested services from the intent invocation if the user already has a handler
+      selected. The User Agent <em class="rfc2119" title="may">may</em> ask the user if they wish to install all
+      or any of the suggested services, just as for any other visit of those pages.
+      </p>
+      <p>
+      The User Agent <em class="rfc2119" title="must">must</em> follow the matching algorithm of the "Matching action
+      and type for delivery" section before delivering
+      the Intent to a suggested service, just as for any Intent delivery.
+      </p>
+      </div>
+
     </div>
 
     <div id="use-cases-and-requirements" class="section">