WebAPI/WebActivities

Introduction

Web Activities is a counter-proposal to Web Intents. It is trying to limit the scope of the API to the following use case: APP A wants to delegate an activity to APP B. Web Activities isn't a discovery API or a communication API. Those things happen in the background and are completely transparent to the caller.

Dependencies

This API depends on two APIs that are not currently part of any specification: System Message Handler and DOMRequest.

Proposed API

 interface ActivityOptions {
   attribute DOMString name;
   attribute Object?   data; // a dictionary
 };
 
 [Constructor(DOMString name)]
 interface ActivityHandlerDescription {
   attribute DOMString name; // default has to be passed to ctor
   attribute DOMString href; // default is current location
   attribute DOMString disposition; // going to be an enum with a default
   attribute boolean   returnValue;
   attribute Object?   filters; // a dictionary
 };
 
 interface ActivityRequestHandler {
   void postResult(any result);
   void postError(DOMString error);
   readonly attribute ActivityOptions source;
 };
 
 [Constructor(ActivityOptions options)]
 interface Activity : DOMRequest {
 };
 
 partial interface Navigator {
   DOMRequest registerActivityHandler(ActivityDescription d);
   void       unregisterActivityHandler(ActivityDescription d);
   bool       isActivityHandlerRegistered(ActivityHandler handler);
 };

Examples

The data structure used in those the activities used in those examples shouldn't be considered as near to anything final. It is just a snapshot on how it could look like. Those examples goal is to underline the use of the API.

Launch an activity

View a png image:

 var a = new Activity({ name: "view", data: { type: "image/png", url: ... }});
 a.onerror = function() { alert("Can't view the image!"); };

Pick an image:

 var a = new Activity({ name: "pick", data: { type: "image/png", multiple: false }});
 a.onsuccess = function() { var image = a.result; doSomethingWithImage(image); });
 a.onsuccess = function() { alert("Failure when trying to pick an image!"); });

Register to handle an activity

View a png image:

 var r = navigator.registerActivityHandler({ name: "view", disposition: "inline",
                                             filters: { type: "image/png" }});
 r.onerror = function() { alert("failed to register activity"); }

View a png/gif image in another page than the current one:

 navigator.registerActivityHandler({ name: "view", href: "image-viewer.html", disposition: "inline",
                                     filters: { type: ["image/png", "image/gif"] }});

View only HTML pages from example.org:

 navigator.registerActivityHandler({ name: "view", filters: { url: /https?:\/\/example.org\/.*/ }});

Handle an activity request

View a png image:

 navigator.setMessageHandler('activity', function(a) {
   // We can't be handling an activity that isn't what we asked, because of |filters|.
   var i = getImageObject();
   i.src = a.source.url;
 
   // We do not call a.postResult() or a.postError() because this activity shouldn't return a value.
 });

Pick an image:

 navigator.setMessageHandler('activity', function(a) {
   var image = getImageToReturn();
   if (!image) {
     a.postError("NoImage");
     return;
   }
   a.postResult({ type: "image/png", url: image });
 });