Labs/Jetpack/JEP/10: Difference between revisions

From MozillaWiki
< Labs‎ | Jetpack‎ | JEP
Jump to navigation Jump to search
 
(19 intermediate revisions by 2 users not shown)
Line 3: Line 3:
== JEP 10 - Clipboard Support ==
== JEP 10 - Clipboard Support ==


* Author: Aza Raskin <aza at mozilla dot com>
* Champion: Aza Raskin <aza at mozilla dot com>
* Champion: Aza Raskin <aza at mozilla dot com>
* Status: Draft
* Editors: Paul O’Shannessy <paul at oshannessy dot com>
* Status: Implementing
* Type: API Track
* Type: API Track
* Created: 26 May 2009
* Created: 26 May 2009
* Reference Implementation: None
* Relevant Bugs: {{bug|495532}} and {{bug|499368}}
* [[Labs/Jetpack/JEPs|JEP Index]]
* [[Labs/Jetpack/JEPs|JEP Index]]


=== Introduction and Rationale ===
=== Introduction and Rationale ===


This JEP describes OS clipboard access to the Jetpack API.
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.
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 [https://developer.mozilla.org/en/Using_the_Clipboard clipboard documentation].
 
As part of this proposal is adding a <code>jetpack.os</code> namespace.


=== Proposal ===
=== Proposal ===


Clipboard access will live at <code>jetpack.os.clipboard</code>. The <code>jetpack.os</code> will provide access to anything that relates to the OS (file access, OS info, etc.)
Clipboard access will live at <code>jetpack.clipboard</code>.


==== Setting the clipboard ====
==== Setting the clipboard ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
jetpack.os.clipboard.set( options )
jetpack.clipboard.set( content )
jetpack.clipboard.set( content, flavor )
</pre>
</pre>


''Arguments''
*'''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).


<code>data</code>: The value to be placed into the system clipboard. It can be anything, a string, a unicode string, a number, an image, and HTML fragment, etc.
'''Examples'''


<code>dataType</code> (optional): Let's Jetpack know what kind of data is being passed in, in [http://en.wikipedia.org/wiki/Internet_media_type mime-type format]. For example, a unicode string would take <code>"text/unicode"</code>, HTML would be <code>"text/html"</code>, and an PNG would be <code>"image/png"</code>. If <code>dataType</code> isn't passed in, Jetpack makes its best guess.
<pre class="brush:js;toolbar:false;">
jetpack.clipboard.set('hello');
jetpack.clipboard.set('<b>Hello</b>', 'html');
</pre>
 
==== Getting the clipboard ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
jetpack.os.clipboard.set( options )
var content = jetpack.clipboard.get();
var content = jetpack.clipboard.get( flavor );
</pre>
</pre>


Often it is necessary to put multiple formats/views of the same data into the clipboard. This way, when another program tries to access the data stored in the system clipboard, it can get the data in the format it knows how to handle.
*'''No arguments''': Assumes a flavor of "plain".
*'''flavor''': A Jetpack clipboard flavor.
 
* '''returns''': The data on the clipboard if available in provided flavor


''Arguments''
'''Examples''':


<code>options</code>: A dictionary containing key-value pairs of <code>data</code> and <code>dataType</code>.
<pre class="brush:js;toolbar:false;">
var contents = jetpack.clipboard.get();
var html = jetpack.clipboard.get( "html" );
</pre>


'''Examples'''
==== Current Flavors ====
 
You can figure out what flavors are currently on the clipboard by using


An example of setting the clipboard in action is as follows:
<pre class="brush:js;toolbar:false;">
var flavors = jetpack.clipboard.getCurrentFlavors();
</pre>


<pre class="brush:js;">
* '''returns''': An array of Jetpack clipboard flavors.
var words = "The quick brown fox jumped over the lazy dog.";
jetpack.os.clipboard.set( words );


var html = "<div>Hello <i>there!</i></div>";
=== Notes on Clipboard Flavors ===
jetpack.os.clipboard.set( html, "text/html" );


jetpack.os.clipboard.set({
==== Additional Reading ====
  "hai2u", "text/plain",
  "hai<b>2u</b>", "text/html",
  "はい２u", "text/unicode"
});
</pre>


==== Getting the clipboard ====
Reading/setting the clipboard requires asking for/giving the format of the data. This is done through "flavors", or slightly modified [http://en.wikipedia.org/wiki/Internet_media_type Internet media types].


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get()</pre>
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.


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


Returns a dictionary of <code>{data:dataType}</code> pairs. If there is nothing in the clipboard, <code>null</code> is returned.
E.g., plain, html, png, gif, video/ogg, audio/ogg


<pre class="brush:js;toolbar:false;">jetpack.os.clipboard.get( dataType )</pre>
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 <code>var img = jetpack.os.clipboard.get( "image" );</code> and not have to worry about what particular image format the clipboard was storing the image in.


''Arguments''
''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.''


<code>dataType</code>: The MIME-type of the data-type desired. Unlike other instances of <code>dataType</code>, everything after the "/" can be omitted, and Jetpack will choose the best available match given an internally pecking order of MIME-types (e.g., unicode is better than plain text, etc.). This enables an author to simple write <code>var img = jetpack.os.clipboard.get( "image" );</code> and not have to worry about what particular image format the clipboard was storing the image in.
==== Jetpack Clipboard Flavors ====


''Return value''
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.


The single value of the requested MIME-type stored in the clipboard. If nothing of that type exists, <code>null</code> is returned.
* '''plain''' - This is normal plain text. It is in unicode (internally equivalent to text/unicode)
* '''html''' - This is HTML.


'''Examples'''
=== Image Support ===


<pre class="brush:js;">
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.
var clip = jetpack.os.clipboard.get();
if( clip["text/plain"] )
  jetpack.notifications.show( clip["text/plain"] );


var img = jetpack.os.clipboard.get( "image" );
Another JEP will be created soon with more information.
$("body").append( img );
</pre>

Latest revision as of 00:04, 11 July 2009

Draft-template-image.png THIS PAGE IS A WORKING DRAFT Pencil-emoji U270F-gray.png
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.

Retrieved from "https://wiki.mozilla.org/index.php?title=Labs/Jetpack/JEP/10&oldid=154579"