WebIntents/MIME Types

From W3C Wiki
< WebIntents
Revision as of 17:47, 28 September 2012 by Gbillock (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Passing MIME type data through Web Intents

A Web Intent payload can have either a string literal or a MIME type. This document describes the payload data format clients must use, and services can expect, when using MIME type specifiers.

When they use a MIME type to describe the passed data, clients and services must format that data as an array of objects with the following schema:


dictionary MimeTypeIntentData {
  URL? url;
  Blob? blob;
  DOMString? text;
  DOMString? filename;
  DOMString? title;
  DOMString? description;
};

For example, an intent invocation to share a web page would look like this:

var intentData = [
   { "url": window.location.href,
     "title": document.title }
];

Note that this is an array with a single object in it.

navigator.startActivity(new Intent(
   {"action": "http://webintents.org/share",
    "type": "text/html", "data":intentData}));

On the receiving side, the service would parse this data as follows:

var sharedUrl = window.intent.data[0].url;
var sharedUrlTitle = window.intent.data[0].title;

And more generically, like this:

for (i = 0; i < window.intent.data.length; ++i) {
   processData(window.intent.data[i]);
}

Services and clients should support multiple exchange items, but if they do not, they should use the MIME parameter "single=true" to designate that they will only honor the first element in the passed list.

Most services will register for a type without this qualification:

image/jpg
image/*
video/*
text/html

If they only handle the first element in the list, they should qualify this with the single=true parameter:

image/jpg;single=true
image/*;single=true
video/*;single=true
text/html;single=true

The format of the passed data is the same in either case: a Javascript array.

The fields in the MimeTypeIntentData schema are all optional, with the following meanings:

url A url pointing to a resource of the indicated type. For example, if the type is "image/png" this would be the url of a png file. Can be a data url.
blob A Blob containing binary data of the indicated type.
text A string containing the text content of the indicated type. Should only be used for text top-level types ("text/", "multipart/", "message/")
title The title provided for the object.
description A description provided for the object.
filename A filename suggested for the object (most useful in cases like view or save actions).

It is expected that for the binary types:

image/
video/
audio/
application/

Either the url or the blob field will be filled.

For text types:

text/
multipart/
message/

it is expected that either the url or the text field will be filled.

The other metadata fields are always optional, and serve as hints to the service (or client) of the intended presentation or name of the resource being exchanged.

Examples

Invoking an image edit intent for a url:

var imageUrl = document.getElementById("main-image").src;
var intent = new Intent(
   {"action":"http://webintents.org/edit",
    "type":"image/jpg",
    "data": [ {"url":imageUrl } ]});
navigator.startActivity(intent, myCallback);

Preparing an application Blob of a feed for an intent:

var feedXmlContents = readXmlForFeed();
BlobBuilder bb = new BlobBuilder();
bb.append(feedXmlContents);
navigator.startActivity(new Intent(
  {"action":"http://webintents.org/subscribe",
   "type":"application/rss+xml",
   "data": [ {"blob":bb.getBlob("application/rss+xml")}]}));

Since the feed contents likely doesn't have the url of the feed itself, the client may want to provide it so the service can more easily manage the subscription:

var feedXmlUrl;
navigator.startActivity(new Intent(
  {"action":"http://webintents.org/subscribe",
   "type":"application/rss+xml",
   "data":[{"blob":bb.getBlob(), "url":feedXmlUrl}]}));

Invoking the share intent for user-edited message:

var shareText = document.forms[0].textBox.value;
navigator.startActivity(new Intent(
  {"action":"http://webintents.org/share",
    "type":"text/plain",
    "data":[{"text" : shareText}]}));

Invoking the share intent for several images:

navigator.startActivity(new Intent(
  {"action":"http://webintents.org/share",
   "type":"image/jpg",
   "data":[
      {"url" : getImageUrl(0), "title":getImageTitle(0)},
      {"url" : getImageUrl(1), "title":getImageTitle(1)},
      {"url" : getImageUrl(2), "title":getImageTitle(2)},
   ]
  }));



As these examples show, the preparation depends on the MIME type. For a binary data type (image/, audio/, video/, application/), the client can sends the data as a Blob. Even if the content is really text, as for the application/rss+xml type feed in the example, it should be wrapped in a Blob container. If this data were passed as text/xml, it should to be sent as raw text in the payload.

Note: It is expected that composite types (message/, multipart/) will play little role in the intents ecosystem.


Deprecated form

Previously, it was recommended that binary types be passed using Blob directly as the data field, and text types be passed using the plain text contents in the data field. This format made use of the extras intent object parameter, which has since been removed from the spec proposal. (That's where the "url" and "filename" were passed.) This usage is now deprecated.