Had moved == 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: [https://groups.google.com/group/mozilla.dev.webapi/browse_thread/thread/a3c6e4c31d04b663/ System Message Handler] and [https://developer.mozilla.org/en/DOM/DOMRequest 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(ActivityHandlerDescription d); void unregisterActivityHandler(ActivityHandlerDescription d); bool isActivityHandlerRegistered(ActivityHandlerDescription handler); }; == More information ==Some various explanation regarding part of this API that are not self-explanatory. === Activity names === Basic activities will have simple names like ''edit'', ''view'', ''pick'' or ''share'' (this is non-exhaustive). A set of basic activities should be defined in the initial specification. Defining will imply specifying how ''data'' should be structured to be considered valid and how the return value (if any) should be structured too. Any other specification will be able to create new activities. For example, a Messaging specification might add 'send-sms'. Any application will be able to create new activities. Any application is able to register itself as handling the activity ''foobar'' and any application is able to start the activity ''foobar''.<br>However, to prevent naming collision, we recommend such proprietary naming to be prefixed with an URL. For example: ''example.org/foobar'' or ''org.example.foobar'' (doesn't matter that much). === Handling an activiy === Handling activities will be done trough [https://groups.google.com/group/mozilla.dev.webapi/browse_thread/thread/a3c6e4c31d04b663/ System Message Handler]. An ''ActivityRequestHandler'' will be passed in the Message. === More information about ActivityOptions === Activities are defined with a name and some data. Those data can be stuff like the image to send, the type of the object or anything the activity will require. Activities with a specific name should havespecific data the handlers will expect to see. <br>That means the initial specification should specify a set of basic activities. === More information about ActivityHandlerDescription === * ''href'': can be used to register an activity handler in another page. Needs to be same origin.* ''disposition'': could be ''window'' or ''inline'' for the moment. ''window'' means it will show a new window/tab. ''inline'' means it will be shown above the current content. This is only a hint for the UA.* ''returnValue'': the UA might want to know if the activity will return a value. For the basic activities (view, edit, etc.) the UA knows that but we need that at least for proprietary activities.<br>This seems to be needed to be able to send a ''success'' or ''error'' event when appropriate. If an application doesn't return a value, the UA might want to send a ''success'' event as soon as an application has been picked. If a value is expected, this event will have to wait ''postResult()'' to be called. Note that UA is expected to send an ''error'' event at some point if neither ''postError'' nor ''postResult'' are called. For example, if the user leaves the application (close the tab on desktop or goes back to the homescreen on a mobile device).* ''filters'': this object should mirror ''data'' from ''ActivityOptions'' but the values for each fields can be an Array of string, a string or a regexp. An activity will be considered as able to handle an activity only if the filters are all satisfied. An array means OR for each items. If there is no filter value for a field, that means it is always satisfied. === Arguments for {un,}registerActivityHandler and isActivityHandlerRegistered === You do not need to pass the same ''ActivityHandlerDescription'' object to have ''registerActivityHandler'', ''unregisterActivityHandler'' and ''isActivityHandlerRegistered'' working. You only need to pass an instance of ''ActivityHandlerDescription'' with the same attribute values. === Declarative registration === Open Web App Manifest should include a way to register activities declaratively. The format would look like this: "activities": { "share": { "filters": { type: [WebAPI"image/png", "image/AppDefinedTelephonygif"], } "href": "foo.html", "disposition": "window" } } For non-installed applications, this API doesn't yet define how to do a declarative registration. However, it doesn't sound very useful for the moment to have such mechanism. However, if it had to be added, adding a new element into the <head> would seem like the most appropriate solution (or using an already existing one). The only advantage of adding a new element inside the <body> is that we don't have to worry about the <head> parsing issues. == 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.onerror = 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"); } Pick a png image and return what the user had picked: var r = navigator.registerActivityHandler({ name: "pick", disposition: "inline", filters: { type: "image/png" }, returnValue: true}); 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\/.*/ }}); Open Web Apps can alternatively register in their webapp manifests. === 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 }); });
