Difference between revisions of "Intents"

From WebOS-Ports
Jump to: navigation, search
(Initial draft)
 
(added Registering Handlers)
Line 4: Line 4:
 
There are a number of common actions that apps should delegate to other apps: sending an email, selecting a picture to insert, sharing a link, picking a contact, etc.
 
There are a number of common actions that apps should delegate to other apps: sending an email, selecting a picture to insert, sharing a link, picking a contact, etc.
 
webOS provided a few custom mechanisms for critical actions and a general mechanism for an app to call another, known app.
 
webOS provided a few custom mechanisms for critical actions and a general mechanism for an app to call another, known app.
These don't generalize well.  Custom mechanisms depend on OS updates.  To share a link, an app had to know the correct launchParam for every app for every service.
+
These don't generalize nor extend well.  Custom mechanisms depend on OS updates.  To share a link, an app had to know the correct launchParam for every app for every service.
  
 
=== Overview ===
 
=== Overview ===
Line 16: Line 16:
 
Any app may register to handle any verb, and optionally the MIME types of data it handles.
 
Any app may register to handle any verb, and optionally the MIME types of data it handles.
 
(We do not expect the same app to "edit" "text/plain" and "image/jpeg".)  Mime types may be generic, such as text/* or image/*.
 
(We do not expect the same app to "edit" "text/plain" and "image/jpeg".)  Mime types may be generic, such as text/* or image/*.
 +
 +
Each verb defines a "data" object to be passed, with required and optional properties.  Apps MAY pass additional data properties, but SHOULD first seek consensus.
  
 
Any app may request any Intent.  As *any* Intent may require user input to complete, the client app SHOULD NOT block on the request.
 
Any app may request any Intent.  As *any* Intent may require user input to complete, the client app SHOULD NOT block on the request.
Line 22: Line 24:
 
When a client app requests a new Intent, the system
 
When a client app requests a new Intent, the system
 
* searches its database to find handlers which can handle the MIME type
 
* searches its database to find handlers which can handle the MIME type
* if there is no match, immediately returns failure to the client and displays UI to the user, informing her that she must install a handler app, and offering to launch Preware.
+
* if there is no match, immediately returns failure to the client and displays system UI to the user, informing her that she must install a handler app, and offering to launch Preware.
* if the user has previously designated a preferred handler for that verb and MIME type, sends a request to the handler without presenting UI.
+
* if the user has previously designated a preferred handler for that verb and MIME type, sends a request to the handler without presenting system UI.
* otherwise, presents a list of handler apps to the user, plus the option Cancel.
+
* otherwise, the system presents a list of handler apps to the user, plus the option Cancel.
 
* if the user cancels, the system returns failure to the client
 
* if the user cancels, the system returns failure to the client
 
* if the user selects an app, the system closes its UI, requests the handler app to do its thing, and waits for a response
 
* if the user selects an app, the system closes its UI, requests the handler app to do its thing, and waits for a response
Line 32: Line 34:
 
The weak point of Intents is that handler apps must be installed before client apps, and the user does not, in general, know she might need a handler app before using a client app.
 
The weak point of Intents is that handler apps must be installed before client apps, and the user does not, in general, know she might need a handler app before using a client app.
 
In general, a verb SHOULD NOT be on the "well-known" list until there is a system default handler, such as a generic file picker that can fulfill a "pick" request of any MIME type.
 
In general, a verb SHOULD NOT be on the "well-known" list until there is a system default handler, such as a generic file picker that can fulfill a "pick" request of any MIME type.
 +
 +
So, handler apps provide either new implementations of actions (for example, an image editor with new features beyond cropping)
 +
or new destinations (sharing to Twitter, rather than just via email or messaging).
  
 
A possible future extension would, when there is no registered handler, for the system to search Preware feeds.
 
A possible future extension would, when there is no registered handler, for the system to search Preware feeds.
That would require Preware to extended to search for app by handled Intents.
+
That would require extending Preware to search for app by handled Intents.
 +
 
 +
=== Registering Handlers ===
 +
An app registers in its appinfo.json.
 +
 
 +
Sample Schema
 +
<code><pre>
 +
"intents": [
 +
  {"name": "edit", "type": "image/*"},
 +
  {"name": "view", "type": "image/*"}
 +
]
 +
</pre></code>
 +
 
 +
The data object is defined by the verb, not by the app, so it is not documented in appinfo.json.
 +
 
 +
When the system calls a handler, it passes the following appParam:
 +
<code><pre>
 +
"intent": {
 +
    "name": "edit",
 +
    "type": "image/jpeg",
 +
    "data": {
 +
        "file": "/media/internal/inProgress/myPhoto.jpg"
 +
    }
 +
}
 +
</pre></code>

Revision as of 17:47, 10 November 2014

Proposed "Lune OS Intents"

Rationale

There are a number of common actions that apps should delegate to other apps: sending an email, selecting a picture to insert, sharing a link, picking a contact, etc. webOS provided a few custom mechanisms for critical actions and a general mechanism for an app to call another, known app. These don't generalize nor extend well. Custom mechanisms depend on OS updates. To share a link, an app had to know the correct launchParam for every app for every service.

Overview

The proposal is provide an extensible mechanism similar to Android Intents/Web Intents/Web Activities.

There is a short list of well-known "verbs", such as "share", "edit", "view", "pick", "subscribe", "save", "dial". New verbs should be developed by consensus, and follow the lead of Android Intents, Web Intents and Web Activities where possible. Verbs should harmonize with Just Type so far as possible. Apps may freely experiment with namespaced verbs, for example "NinjaGroup:slice".

Any app may register to handle any verb, and optionally the MIME types of data it handles. (We do not expect the same app to "edit" "text/plain" and "image/jpeg".) Mime types may be generic, such as text/* or image/*.

Each verb defines a "data" object to be passed, with required and optional properties. Apps MAY pass additional data properties, but SHOULD first seek consensus.

Any app may request any Intent. As *any* Intent may require user input to complete, the client app SHOULD NOT block on the request. Intents always return at least success or failure. The simplest failure is that there was no registered handler.

When a client app requests a new Intent, the system

  • searches its database to find handlers which can handle the MIME type
  • if there is no match, immediately returns failure to the client and displays system UI to the user, informing her that she must install a handler app, and offering to launch Preware.
  • if the user has previously designated a preferred handler for that verb and MIME type, sends a request to the handler without presenting system UI.
  • otherwise, the system presents a list of handler apps to the user, plus the option Cancel.
  • if the user cancels, the system returns failure to the client
  • if the user selects an app, the system closes its UI, requests the handler app to do its thing, and waits for a response
  • when the handler responds to the request (which might be hours later), passes the response to the client (without further system UI).

User Experience

The weak point of Intents is that handler apps must be installed before client apps, and the user does not, in general, know she might need a handler app before using a client app. In general, a verb SHOULD NOT be on the "well-known" list until there is a system default handler, such as a generic file picker that can fulfill a "pick" request of any MIME type.

So, handler apps provide either new implementations of actions (for example, an image editor with new features beyond cropping) or new destinations (sharing to Twitter, rather than just via email or messaging).

A possible future extension would, when there is no registered handler, for the system to search Preware feeds. That would require extending Preware to search for app by handled Intents.

Registering Handlers

An app registers in its appinfo.json.

Sample Schema

"intents": [
   {"name": "edit", "type": "image/*"},
   {"name": "view", "type": "image/*"}
] 

The data object is defined by the verb, not by the app, so it is not documented in appinfo.json.

When the system calls a handler, it passes the following appParam:

"intent": {
    "name": "edit",
    "type": "image/jpeg",
    "data": {
        "file": "/media/internal/inProgress/myPhoto.jpg"
    }
}