Confirmed users
1,340
edits
WebAPI/WebActivities: Difference between revisions
no edit summary
(Some examples) |
No edit summary |
||
| (15 intermediate revisions by 6 users not shown) | |||
| Line 34: | Line 34: | ||
partial interface Navigator { | partial interface Navigator { | ||
DOMRequest registerActivityHandler( | DOMRequest registerActivityHandler(ActivityHandlerDescription d); | ||
void unregisterActivityHandler( | void unregisterActivityHandler(ActivityHandlerDescription d); | ||
bool isActivityHandlerRegistered( | 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 have | |||
specific 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: ["image/png", "image/gif"], | |||
} | |||
"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 == | == 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. | 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 === | === Launch an activity === | ||
View a png image: | View a png image: | ||
| Line 49: | Line 98: | ||
var a = new Activity({ name: "pick", data: { type: "image/png", multiple: false }}); | var a = new Activity({ name: "pick", data: { type: "image/png", multiple: false }}); | ||
a.onsuccess = function() { var image = a.result; doSomethingWithImage(image); }); | a.onsuccess = function() { var image = a.result; doSomethingWithImage(image); }); | ||
a. | a.onerror = function() { alert("Failure when trying to pick an image!"); }); | ||
=== Register to handle an activity === | === Register to handle an activity === | ||
| Line 56: | Line 105: | ||
filters: { type: "image/png" }}); | filters: { type: "image/png" }}); | ||
r.onerror = function() { alert("failed to register activity"); } | 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: | View a png/gif image in another page than the current one: | ||
| Line 63: | Line 118: | ||
View only HTML pages from example.org: | View only HTML pages from example.org: | ||
navigator.registerActivityHandler({ name: "view", filters: { url: /https?:\/\/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 === | === Handle an activity request === | ||
| Line 83: | Line 140: | ||
a.postResult({ type: "image/png", url: image }); | a.postResult({ type: "image/png", url: image }); | ||
}); | }); | ||
[[Category:Web APIs]] | |||