--- a/spec/Overview-respec.html Sun Jan 29 19:07:35 2012 -0800
+++ b/spec/Overview-respec.html Tue Jan 31 13:57:04 2012 -0800
@@ -108,22 +108,24 @@
exchanged data.
</p>
<p>
- An Intent is an action to be performed by a service. It consists of an
- "action" string which tells the service what kind of activity the user
- expects to be performed (e.g., "share" or "edit"), a "type" string which
+ An Intent is a user-initiated action delegated to be performed by a service.
+ It consists of an "action" string which tells the service what kind of activity
+ the user expects to be performed (i.e. "share" or "edit"), a "type" string which
specifies the data payload the service should expect, and the data payload
itself.
</p>
<p>
- A client requests an Intent be handled, the User Agent allows the
- user to select which service to use, and the service performs the action
- of the Intent, possibly using data passed as input in the Intent.
- The service may return data as output to the client.
+ The lifecycle of an Intent is that first, a client requests an Intent be
+ handled. This Intent data is then passed to the User Agent, which allows the
+ user to select which of potentially many possible services to use. Then
+ the service is passed the Intent data and is provided a UI by the User
+ Agent in which to perform the action specified in the Intent. Finally,
+ the service may also return data as output back to the client.
</p>
<p>
Web Intents provides a declarative syntax that allows
- services to list the Intents they handle. Using this method, pages mark
- up what actions they can handle what data types they expect.
+ services to list the Intents they handle. Using this method, services mark
+ up what actions they can handle and which data types they expect.
</p>
<section>
<h3>Example</h3>
@@ -141,24 +143,25 @@
"text/uri-list;type=image/jpeg",
getImageDataURI(...));
navigator.startActivity(intent, imageEdited);
- });
+ };
function imageEdited(data) {
document.getElementById('image').src = data;
}
</pre>
<p>
- This assumes an image editor exists which can consume images specified as
- URIs (including data URIs), and produces a result in the same format. For
- instance, one such editor might be a meme-maker—an application allowing
- the user to place humorous messages on top of pictures they take.
+ This code delegates image editing to third-party applications which can
+ consume images specified as URIs (including data URIs), and produce
+ results in the same format. For instance, one such editor might be
+ a meme-maker—an application allowing the user to place humorous
+ messages on pictures they take.
</p>
<p>
- Now that a picture has been selected and meme text added, the user
- undoubtedly wants to share the result with friends. Again, the photo
- hosting application may not have built-in sharing capabilities, but by
- adding a "share" button near images, and with this kind of accompany code,
- it can accomplish this integration:
+ Now that a picture has been edited in the selected service, and meme text
+ added, the user undoubtedly wants to share the result with friends. Again,
+ the photo hosting application may not have built-in sharing capabilities,
+ but by adding a <b>Share</b> button near images, and with this kind of
+ accompanying code, it can accomplish this integration:
</p>
<pre class="example">
document.getElementById('share-photo').onclick = function() {
@@ -166,22 +169,33 @@
"text/uri-list;type=image/jpeg",
getPublicURIForImage(...));
navigator.startActivity(intent);
- });
+ };
</pre>
<p>
+ This code delegates sharing functionality to an existing services chosen
+ by the user which are capable of sharing urls. So a social networking site
+ selected by the user might produce a status update with a thumbnail.
+ A blogging site might provide a UI allowing the user to post the picture.
+ <p>
Note that with this integration, other more high-minded services can be
selected by the user as well. Instead of using the service to add funny
- captions, the user can utilize a sophisticated photo editing application
+ captions, the user might utilize a sophisticated photo editing application
to adjust exposure, remove red-eye, or do any number of other
transformations on the image. The user can have many such tools
- registered, and choose any of that set to use at any given time. The photo
- hosting application isn't controlling which such application any given
- user uses, it is loosely coupled with such appliations by providing the
- data necessary for them to carry out their task and controls allowing the
+ registered, and choose any of that set to use for any given image editing
+ task. The photo hosting application isn't controlling which such application
+ any given user uses; it is loosely coupled with such applications by providing the
+ data necessary for them to carry out their task, and controls allowing the
user to launch these activities on the data.
</p>
<p>
- On the service page, it needs to register itself as a service, and
+ In this way, an Intent is like the dual of a hyperlink. With a hyperlink,
+ the source page specifies the exact URL to be navigated to. With an
+ Intent, the source page specifies the nature of the task to be done, and the
+ user can select any of a number of applications to be used to complete the task.
+ </p>
+ <p>
+ On the service side, the page needs to register itself as a Web Intents service, and
handle the incoming intent data, possibly producing a response. That is
done with this kind of code:
</p>
@@ -197,20 +211,20 @@
if (window.intent) {
setImageContentURI(window.intent.data);
}
- }
+ };
document.getElementById('save-button').onclick = function() {
- window.intent.postResult(getImageDataURI(...));
- }
+ window.intent.postReply(getImageDataURI(...));
+ };
</script>
</pre>
<p>
- The assumed pieces here are functions which deal with the application's
- image display, for instance putting the image into a canvas and taking it back out
- again as a data URI.
+ The assumed pieces here (on both client and service pages) are functions
+ which deal with the application's image display, for instance putting the
+ image into a canvas and taking it back out again as a data URI. Or
+ producing the public URI of the image on the site.
</p>
</section>
- </section>
<section>
<h2>Terminology</h2>
@@ -221,31 +235,31 @@
<section>
<h3>Actors</h3>
<p>
- A <dfn>Client</dfn> is a web page which creates an intent and invokes
+ A <dfn>Client</dfn> is a web page which creates an Intent and invokes
it.
</p>
<p>
- A <dfn>Service</dfn> is a web page which can handle a Web Intent,
+ A <dfn>Service</dfn> is a web page which can handle an Intent,
possibly returning a piece of data to the calling Client page.
</p>
</section>
<section>
- <h3>Life cycle of intents</h3>
+ <h3>Life cycle of Intents</h3>
<p>
<dfn>Registration</dfn> is how a Service page informs the User Agent
that it is capable of handling Intents.
</p>
<p>
<dfn>Invocation</dfn> refers to the API by which a Client page
- dispatches an intent for handling.
+ dispatches an Intent for handling.
</p>
<p>
<dfn>Selection</dfn> is the mechanism in which the User Agent decides
- which service will handle a particular intent.
+ which Service will handle a particular Intent.
</p>
<p>
- <dfn>Delivery</dfn> is the means by which the User Agent hands intent
- data to a Service page for handling.
+ <dfn>Delivery</dfn> is the means by which the User Agent passes an Intent
+ to a Service page for handling.
</p>
<p>
<dfn>Response</dfn> is the means in which the Service can respond to an
@@ -260,10 +274,10 @@
<section>
<h3>Intent object</h3>
<p>
- The client requests a specific intent handler and optionally sends in a callback to
- receive data from the service. The browser mediates the service selection by
- enumerating the list of registered services that match the requested
- intent action and type. The user is then able to select which service should handle the intent.
+ The Intent object models a particular task which can be requested by
+ handled by client pages. It is left up to the client page whether to
+ launch multiple Intents simultaneously. Specific Intent objects are
+ immutable once created.
</p>
<dl title='[Constructor(in string action, in string type, in any data) raises DOMException] interface Intent' class='idl'>
<dt>readonly attribute DOMString action</dt>
@@ -272,44 +286,49 @@
constructor MUST throw an exception.</dd>
<dt>readonly attribute DOMString type</dt>
<dd>The data payload MUST be described by the type parameter.
- Recommended type strings are MIME strings and self-documenting urls. The
+ Recommended type strings are MIME strings or self-documenting urls. The
string MUST NOT be empty, or the constructor MUST throw an exception.</dd>
<dt>readonly attribute any data</dt>
- <dd>The object used MUST be a Transferable or an object upon which the
- structured clone algorithm can be performed, or the constructor MUST
+ <dd>The object used MUST be an object upon which the structured clone
+ algorithm can be performed, including Transferables, or the constructor MUST
throw an exception.</dd>
<dt>void postResult(in any data)</dt>
- <dd>The payload passed to this method will be returned to the onSuccess
+ <dd><b>Only present when the Intent object is delivered to the
+ Service page.</b> The payload passed to this method will be returned to the onSuccess
callback registered by the client page in the startActivity call (if any).
- The payload must be a Transferable object [[!HTML5]] upon which the structured
- clone algorithm can be performed.</dd>
+ The payload must be an object upon which the structured clone algorithm can be
+ performed, including Transferables. [[!HTML5]] </dd>
<dt>void postFailure(in any data)</dt>
- <dd>The payload passed to this method will be returned to the onFailure
+ <dd><b>Only present when the Intent object is delivered to the Service
+ page.</b> The payload passed to this method will be returned to the onFailure
callback registered by the client page in the startActivity call (if any).
- The playload must be a Transferable object upon which the structured
- clone algorithm can be performed.</dd>
+ The playload must be an object upon which the structured clone algorithm
+ can be performed, including Transferables. [[!HTML5]]</dd>
</dl>
</section>
<section>
<h3>Invocation API</h3>
<p>
- The client invokes an intent by constructing an object as above and invoking
- a <code>navigator.startActivity</code> function on it. The callbacks are invoked when
- the intent has been handled.
+ The client invokes an intent by constructing an Intent object as above and invoking
+ the <code>navigator.startActivity</code> function on it. The callbacks
+ passed to this method are invoked when the intent has been handled by the service.
+ The User Agent will mediate the service selection by enumerating the list of
+ registered services that match the requested
+ intent action and type. The user is then able to select which service should handle the intent.
</p>
<dl title='[NoInterfaceObject] interface Intents' class='idl'>
<dt>void startActivity (in Intent intent, in optional onSuccess, in optional onFailure)</dt>
- <dd>Called to invoke an intent service. The intent object is described
+ <dd>Called to invoke an intent service. The Intent object is described
above. The onSuccess handler, if any, will be called by the user agent if
the service is dispatched, processes the intent, and calls postResult on
- the intent object it receives. The handler will be invoked with one
+ the Intent object it receives. The handler will be invoked with one
parameter: the data received from the service.
The onFailure handler, if any, will be called by the user agent if
the service cannot be dispatched, if the user aborts the selection
process, or if a service was chosen, received the intent, processes the intent,
- and calls postFailure on the intent object it receives. The handler will be invoked with one
+ and calls postFailure on the Intent object it receives. The handler will be invoked with one
parameter: the data received from the service.
User Agents SHOULD restrict this method to only be successfully callable within the
context of an explicit user gesture.
@@ -329,7 +348,7 @@
<section>
<h3>Delivery and Response API</h3>
<p>
- When the user agent loads a service page to handle an intent invocation, it
+ When the user agent loads a Service page to handle an intent invocation, it
will place a <code>window.intent</code> object in the scope of the page.
</p>
@@ -371,9 +390,7 @@
In other words, in the browsing context in which the intent is originally
delivered, the intent data MUST be available to pages in a redirect sequence
when they are in the same origin as that to which it was originally
- delivered, but MUST NOT be available to any other pages. If the user navigates to a
- different URL, even within the same origin, the intent data MUST NOT be made
- available.
+ delivered, but MUST NOT be available to any other pages.
</p>
</section>
@@ -388,20 +405,20 @@
exactly, and the type strings must match exactly except for possible [[!RFC2046]]
MIME subtype wildcards.
<pre>
- <!ENTITY % Disposition "window|inline">
+ <!ENTITY % Disposition "{window|inline}">
<!ELEMENT INTENT - O EMPTY -- a Web Intents registration →
<!ATTLIST INTENT
- action %URI; #REQUIRED -- URI specifying action --
- type %ContentTypes; #REQUIRED -- advisory content type --
- href %URI; #IMPLIED -- URI for linked resource --
- title CDATA #IMPLIED -- service title --
- disposition %Disposition (window) -- where the service is created --
+ action %URI; #IMPLIED -- URI specifying action --
+ type %ContentTypes,%URI; #IMPLIED -- advisory content type --
+ href %URI; #IMPLIED -- URI for linked resource --
+ title %i18n; #IMPLIED -- service title --
+ disposition %Disposition "window" -- where the service is created --
>
</pre>
</p>
<p>
- The <code>dispositon</code> attribute allows a service to choose which
+ The <code>disposition</code> attribute allows a service to choose which
context to be opened in. The User Agent MUST NOT allow the client any
ability to change the disposition. The <code>window</code> disposition means
that the service is opened in a new tab or window context. The
@@ -411,8 +428,27 @@
under the control of the client page.
</p>
<p>
- The User Agent SHOULD discard any registration markup which is not
- same-origin.
+ The User Agent MUST not obey any registration markup which is not
+ same-origin. That is, a page may only register <code>href</code> attributes
+ for other service handlers on its same origin. A page may register itself
+ as a Service handler, by leaving this attribute empty.
+ </p>
+ <p>
+ If the <code>title</code> attribute is missing, the User Agent SHOULD
+ utilize the title of the registered Service page to guide the user-visible
+ indicator of that Service during Selection.
+ </p>
+ <p>
+ If the <code>action</code> attribute is missing, the intent Service is
+ assumed to handle display of the provided type(s) in that attribute.
+ </p>
+ <p>
+ If the <code>type</code> attribute is missing, the intent Service is
+ assumed to be registered specifically for a <code>text/plain</code> type.
+ </p>
+ <p>
+ The User Agent SHOULD not obey any registration markup which has both
+ <code>action</code> and <code>type</code> attributes missing.
</p>
</section>