W3C

Clipboard Operations for the Web 1.0: Copy, Paste, Drag and Drop.

W3C Working Draft 15 November 2006

This version:
http://www.w3.org/TR/2006/WD-clipboard-apis-20061115/
Latest version:
http://www.w3.org/TR/clipboard-apis
Editors:
Charles McCathieNevile, Opera Software
Doug Schepers, Vectoreal

Abstract

This document describes apis for clipboard operations such as copy/cut and paste, or drag and drop in web applications.


Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is the First Public Working Draft prepared of Clipboard Operations from the Web API group, part of the Rich Web Client Activity. In large part it describes the functionalities as implemented in Internet Explorer, and has not been sufficiently tested in other browsers yet. The intention of this document is where possible to specify what actually works in current browsers, or is a simple target for them to improve interoperability, rather than adding new features. A second version of this specification may be produced which extends that functionality in various ways which have proven useful.

This document is published to solicit comments from interested parties. All comments are welcome and may be sent to public-webapi@w3.org. All messages received at this address are viewable in a public archive. After reviewing comments and further feedback, the Working Group intends to publish a new Working Draft of this document at the beginning of 2007.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

Introduction

This section is informative

This specification defines the common clipboard operations of cutting, copying and pasting, in such a way that they are exposed to Web Applications and can be adapted to provide advanced functionalities. Its goal is to provide for compatibility where possible with existing implmentations.

Recognising that "drag and drop" operations are essentially a common user interface extension of cut or copy, move, and paste, it also defines how the events currently implemented for "drag and drop" operations relate to the less device-specific approach of general clipboard operations.

A common interface design in the traditional WIMP (Windows, Icons, Mouse Pointer) interface is to move the pointer to an icon or to a highlighted selection, press the mouse key and drag a copy of the icon to the target where s/he wants to drop the object, then release the mouse key. There are, of course, many alternatives. In a graphic user interface without a mouse a user might select an object for dragging through a context menu, navigate to another object through standard navigation, and then select to drop the held object.

Use Cases

This section is informative

There are many use cases for being able to change the default clipboard operations (cut/copy/paste, and the related drag-and-drop). We have colected a few samples to demonstrate possible uses, although these may not all be supoprted by this specification.

Advanced application interfaces

Allowing for interfaces that use a thumbnail image to refer to a block of content, which can then be dragged to insert the block of content represented in another part of a web page. The common Drag-and-drop pardigm must be implementable in such a way that it is accessible to users who are unable to use a mouse (such as those on a phone where there is no mouse) and must rely on keyboard or other interfaces.

Mathematical information

With content such as mathematics, simply copying rendered text and pasting it into another application generally leads to most of the semantics being lost. The following example, when copied, typically adds two lines containing the text "2 x = 7" to the clipboard. But in the MathML source of this text, and for any human reader familiar with normal western conventions for mathematical layout, this leads to incorrect copying. The first line would often be better, if copied as plain text, as "2^x = 7", or if the XML source could be placed in the clipboard with the appropriate transformation occurring when pasting.

Example 1: Mathematical information

The equations "2^x = 7" and "2x = 7" represented in Presentation MathML contain the same sequence of characters, but have different semantics.

Rich content editing

Similarly, when copying text which contains hyperlinks or other structure, it is often useful to be able to reformat the content to preserve important information.

And in order to make web applications which allow the manipulation of rich text, or of graphic content such as SVG, it is useful to provide a mechanism that allows for copying more than just the rendered content.

Conformance

The terms must, should, may, must not, should not, are used in this document in accordance with [RFC2119]. A conformant implementation of this specification meets all requirements identified by the use of these terms.

Security issues

Enabling authors to change what is copied by a user, or to make an automated copy of something that was never selected and allowing unrestricted calls to paste information can raise various security concerns. If these operations are allowed to transfer data across documents from different sources then there are even greater risks imaginable. On the other hand there are valid reasons for allowing this in the right circumstances.

An example scenario of a problem is where a user selects a link and copies it, but a different link is copied to the clipboard. The effect of this can range from an unexpected result on pasting to an attempted "phishing" attack.

Authors be aware that User Agents will typically restrict what is possible to content they consider "safe", or trusted by the user. For example, it may not be possible to launch some of the operations from script, such as requiring an actual (not simulated or script-generated) user action to paste or drop.

Implementors should carefully consider the security implications of implementing this specification, and provide appropriate protection for users against malicious use, such as restricting access to the functionalities according to how trusted the source of a function call is, or informing the user when something other than rendered content is copied to the clipboard.

This specification will attempt to highlight all areas where possible security issues arise, but the final responsibility for making decisions about what to allow rests with user agent implementors. Note that this is not done in the current draft.

@@Issue: identify what the restrictions generally used are, as some guidance on interoperability

User Interface Issues

This section is informative

This specification does not define all the user interface modes that can be used to select content, but this section attempts to provide a survey of some common ones. Authors and implementors should be aware that the precise User Interface details will vary according to the use case and platform, with different methods applying for

Many of these user interfaces have developed common interaction paradigms (in the case of the common mouse/keyboard/window interface there are several which are expected to interact seamlessly) for copy and paste at least. Other may be less common and have no emerging convention, while other interfaces may be developed. In each case, the events and results described below should be mapped by the platform to particular user interaction.

Another method that can be used is to provide a copy/paste and copy special/paste special set of operations, to distinguish between copying simple or structured content to the clipboard.

Select, Cut, Copy, Paste

These are well-understood operations for users. There are events fired during selection, cut/copy and paste in some systems already which can be captured, cancelled, and whose effects can be overwritten. In particular, what is copied to the clipboard may be the rendered content that is selected, or may be some other modified version. (See security implications and annoying the user, and the setData method's ).

Each copy-paste operation has 4 distinct phases:

Source Selection
This typically uses the standard selection mechanism for the system User Interface to set the source node for any clipboard operation.
Copy
This uses the setData method to copy the source node to the clipboardData object. It may also copy the data to a dataTransfer object. @@Issue: This makes drag and drop more flexible, e.g. for accessibility. What is the downside?
Target Selection/Content Confirmation
In a typical usage scenario, this will in fact be the same user interface mechanism that is used for Source Selection. It sets the current target.
Content Insertion into Target
This fires a paste event on the current target. The default effect is that where applicable (for example in editable text such as an input) the content which is held in the clipboard is inserted at the target.

The source content may be either structured or unstructured. Unstructured content is of a single simple type such as text or an image bitmap. Structured content is composed either of mixed content types, or a combination of several items of the same content type. @@Issue: Actually, this isn't how it works in IE. We should think about this bit more...

Selection may be accomplished by a number of means - see User Interface Issues above.

copy places a copy of the object selected into a clipboard. The current selection must not be affected.

cut should delete the object selected, and place it into the clipboard. In the case of read-only content (such as a document which is not editable by the user) the content should not be removed, but a copy should be placed in the keyboard as for a copy operation. [@@Issue: nice idea, does it reflect current reality? Opera/Safari on Mac don't do that...].

paste triggers an event on the current target (usually the current selection). @@Issue: For drag and drop compatibility should it trigger drop and paste, or vice versa?

Drag and drop processing

Drag and drop is essentially a special case of a cut or copy, moving to select some new target, and then a paste operation, which is implemented for mouse-based devices. The main differences in drag-and-drop are that the object being dragged is can fire a dragover event on various possible targets before being dropped onto them, and that the object selected may be copied to a temporary drag-specific clipboard. Compare the following phases with those in copy and paste:

Source Selection
This may use the same user interface mechanism as for copy and paste (@@Issue: and fire the same events?).
Copy Initiation
In a typical Drag and Drop implementation, this event is initiated by dragging the currently selected source. This must fire a dragstart event. It must copy the source node into dataTransfer. It should set the effectAllowed property to determine whether a drag operation copies, moves, links, etc the source node. See [MDT] for further documentation of how this works in Internet Explorer. (@@Issue: Can it just use the copy interface? Where does dataTransfer come from? Can you start a drag using the existing copy buffer?)
Target Selection
This process is repeated, and fires three events: dragenter, dragover, and dragleave. This may be the same mechanism as used for selection, although typical implementations provide a seperate mechanism. These events should not fired on the source, so until there is a dragenter event fired, a drop event should not be fired. Any action which would have caused a drop to be fired before any dragenter event has fired should cancel the drag.
Content Insertion into Target
When a drop operation is performed, a drop event is fired at the target. In order to protect the user from pasting unexpected content, user agents may not allow this event to be fired when not triggered by direct user interaction. In a drag operation this normally destroys the dataTransfer object. @@Issue: what if the operation is not successful?

However it is implemented in an interface, drag and drop operations must have a starting point (e.g. where the mouse was clicked, or the when a selection or element is selected for the drag), may have any number of intermediate steps (elements that the mouse moves over during a drag, or elements that the user picks as possible drop points as she cycles through possibilities), and must either have an end point (the element above which the mouse button was released, or the element that was finally selected), or be canceled. The end point must be the last element selected as a possible drop point before the drop occurs. If there is no dragenter event fired after a dragstart, then the drop event should be cancelled, but may be fired on the source node.

Then, regardless of whether the event was canceled or not, drag feedback (e.g. the mouse cursor or other clear indication to the user) should be updated to match the kind of operation indicated by the event's dataTransfer object's dropEffect attribute, as follows: @@Issue: More info about setting the dropEffect would be useful

dropEffect Drag operation
none No operation allowed.
copy Data will be copied.
link Data will be linked.
move Data will be moved.

The following events are involved in the drag-and-drop model. They all use the DragEvent interface. (these fire on-* events in IE 5+ @@Issue: and IE7?

Event Name Target Bubbles/Cancelable? (yes/yes unless noted) dataTransfer dropEffect Default Action
dragstart Source node The setData method places the source node in either clipboardData or dataTransfer. @@Issue: if it sets clipboardData is should also set dataTransfer, no? none Initiate the drag-and-drop operation
drag Source node âÄî none Continue the drag-and-drop operation
dragenter Immediate user selection or the body element âÄî Based on effectAllowed value Change the current target element from the immediate user selection to the element this event is fired on. @@Issue: If it is fired on the body, this text isn't right...
dragleave Previous target element Not cancelable âÄî none None
dragover Current target element âÄî Based on effectAllowed value Reset dropEffect based on effectAllowed value
drop Current target element getData() returns data set in dragstart event Current drag operation Varies
dragend Source node âÄî none Varies

Setting and getting the data to be transferred

Internet Explorer provides 3 methods for the clipboardData and dataTransfer objects:

setData()
This takes one or two parameters. The first must be set to either 'text' or 'URL' (case-insensitive).
getData()
This takes one parameter, that allows the target to request a specific type of data.
clearData()
This clears the data from the object.

Extensibility

Don't extend this yet, we haven't even specified it. Thanks!!!

Glossary

Immediate User Selection
Source Node
The node which is the source of the object to be copied, dragged, etc.
Target Element
The node at which a paste or drop event will be fired.

References

Normative references:

[RFC2119]
The specification for how to use english to specify normativity, as if it were a technical language. Available at http://rfc.net/rfc2119.html

Informative References

[MDT]
Microsoft's information on Clipboard Operations in Internet Explorer. Available at http://msdn.microsoft.com/library/default.asp?url=/workshop/author/datatransfer/overview.asp.
[SCP]
Paul Libbrecht, submission for Web API WG and WHAT-WG. Available at http://www.activemath.org/~paul/tmp/Ideal-Browser-Behaviour.html.
[WHAT-WA]
Web Applications 1.0 Working Draft, I Hickson ed. Unstable draft, available at http://whatwg.org/specs/web-apps/current-work/.

Acknowledgements

This section is informative

The editors would like to acknowledge their intellectual debt to the documentation of Data Transfer functionalities from Microsoft [MDT]. The draft specification of them from the WHAT Working Group published as part of their draft "Web Applications 1.0" [WHAT-WA] which essentially repeats the drag-and-drop-specific parts of that were heavily used to prepare the initial drafts of this specification. We are also grateful for the draft "safe copy and paste" [SCP] from Paul Libbrecht.

We would like to acknowledge the contributions made by the following:

Shawn Carnell, Daniel Dardailler, Al Gilman, Lachlan Hunt, Aaron Leventhal, Jim Ley, Paul Libbrecht, "Martijn", Dave Poehlman, "ROBO Design", Janina Sajka, Rich Schwerdtfeger, Jonas Sicking, Maciej Stachowiak, Mihai Sucan, Tom Wlodkowski