Labs/Jetpack/JEP/10

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

JEP 10 - Clipboard Support

• Champion: Aza Raskin <aza at mozilla dot com>
• Editors: Paul O’Shannessy <paul at oshannessy dot com>
• Status: Implementing
• Type: API Track
• Created: 26 May 2009
• Reference Implementation: None
• Relevant Bugs: bug 495532 and bug 499368
• JEP Index

Introduction and Rationale

This JEP describes OS clipboard access for the Jetpack API.

A number of Jetpacks have already implemented their own versions of clipboard access. It makes sense to unify the API and allow for a clean way for Jetpacks to get and set the clipboard in a variety of formats. The proposed API is informed by the MDC clipboard documentation.

Proposal

Clipboard access will live at jetpack.clipboard.

Setting the clipboard

jetpack.clipboard.set( content )
jetpack.clipboard.set( content, flavor )

• content: The content to put on the clipboard. If no other arguments are supplied, the content is assumed to be of flavor "plain". For now, this can only be text or an image. In the future, it can be anything that is place-able on the system clipboard.
• flavor: A Jetpack clipboard flavor (see below).

Examples

jetpack.clipboard.set('hello');
jetpack.clipboard.set('<b>Hello</b>', 'html');

Getting the clipboard

var content = jetpack.clipboard.get();
var content = jetpack.clipboard.get( flavor );

• No arguments: Assumes a flavor of "plain".
• flavor: A Jetpack clipboard flavor.

• returns: The data on the clipboard if available in provided flavor

Examples:

var contents = jetpack.clipboard.get();
var html = jetpack.clipboard.get( "html" );

Current Flavors

You can figure out what flavors are currently on the clipboard by using

var flavors = jetpack.clipboard.getCurrentFlavors();

• returns: An array of Jetpack clipboard flavors.

Notes on Clipboard Flavors

Additional Reading

Reading/setting the clipboard requires asking for/giving the format of the data. This is done through "flavors", or slightly modified Internet media types.

Mime-types are often redundant, though. Take for example, "text/html". There are no other mime-types ending in "html" so "html" is enough to uniquely identify the flavor. In fact, it appears that the only ambiguity exists around some "audio/" and "video/" mime-types which share the same after-the-slash type.

For Jetpack clipboard flavors, the before-the-slash type is left off unless needed to resolve a rare ambiguity.

E.g., plain, html, png, gif, video/ogg, audio/ogg

On the flip side. Everything after the "/" can be omitted if you don't care about a specific type being returned. Jetpack will choose an available match given a possibly arbitrary ordering MIME-types (e.g., if you pass in "image" Jetpack may return an image in PNG format). This enables an author to simple write var img = jetpack.os.clipboard.get( "image" ); and not have to worry about what particular image format the clipboard was storing the image in.

Odd footnote: It appears in the documentation for the clipboard on MDC that there exists a "text/unicode" flavor. However, I can find no mention of it in the Internet media type spec.

Jetpack Clipboard Flavors

As mentioned above, we've made it a bit easier to use flavors. We haven't implemented all flavors, so for now there are only the text related flavors.

• plain - This is normal plain text. It is in unicode (internally equivalent to text/unicode)
• html - This is HTML.

Image Support

Images are not supported yet. We have yet to finalize the API around image use & the clipboard. For now you should get errors if you try to set or get the clipboard with an image.

Another JEP will be created soon with more information.