This is a Clipboard API event specification draft edited by Hallvord R. M. Steen, Opera Software. Although I've used W3C stylesheets for convenience this spec is not currently adopted by the W3C.
When the user initiates a copy operation, the implementation must fire a copy event. Its default action is to place the selected data on the clipboard. If there is no selection, the event has no default action.
| Type | copy |
|---|---|
| Interface | ClipboardEvent |
| Cancelable | Yes |
| Bubbles | Yes |
| Target | Elements |
When the user initiates a cut operation, the implementation must fire a cut event. In an editable context, its default action is to place the selected data on the clipboard and remove the selection from the document.
In a non-editable context, or if there is no selection, the cut event has no default action.
| Type | cut |
|---|---|
| Interface | ClipboardEvent |
| Cancelable | Yes |
| Bubbles | Yes |
| Target | Elements |
When the user initiates a paste operation, the implementation must fire a paste event.
If the cursor is in an editable element, the default action is to insert clipboard data in the most suitable format supported for the given context.
In an editable context, the paste event's target property refers to the element that contains the start of the selection. In a non-editable document, the event is targeted at a node focused by clicking or by an interactive cursor. If the node that has focus is not a text node, the event is targeted at the BODY element.
The paste event has no default action in a non-editable context.
| Type | paste |
|---|---|
| Interface | ClipboardEvent |
| Cancelable | Yes |
| Bubbles | Yes |
| Target | Element |
How should we define the relationship to the HTML5 DataTransfer interface? Can DataTransfer inherit from ClipboardData and add the drag-and-drop stuff, or should we just defer to HTML5 for all of this?
interface ClipboardData {
void clearData( in optional DOMString type );
DOMString getData(in DOMString type);
void setData(in DOMString type, in DOMString data);
DOMStringList types;
}
The types property returns a DOMStringList of MIME type strings. [RFC2046]. In the paste event, it lists those formats available on the clipboard the implementation supports returning to the script. In the copy and cut events, the types property returns a list of supported formats for the copy operation - for example, if the implementation supports copying plain text and HTML it would return a DOMStringList with the values 'text/plain' and 'text/html'.
The order of these values is undefined.
This .types spec is slightly different from the HTML5 DnD .types - consistent enough to make sense to authors and implementers?
Calling getData() from within a paste event handler will return the clipboard data in the specified format. An implementation must support 'text/plain' and should support 'text/html' to retrieve any HTML formatted data on the system clipboard.
If getData() is not called from within a paste event handler, or if the type is not available, the method returns undefined. Note: IE allows this, but it seems to go against user expectations
HTML5 says return empty string if data of that type is not found. WebKit returns undefined though..
If the method is called with too many or too few arguments, it throws a syntax error exception.
Note: for compatibility purposes, the value 'text' (case-insensitive) must be treated as 'text/plain'.
Method exists in WebKit but doesn't seem to do anything
Calling setData() from within an event handler will modify the data which will be placed on the clipboard, for the specified format.
If the type argument is not supported, the setData() call does nothing.
setData() with unsupported type throws in IE
Calling setData() from a paste event handler will modify the data before it is inserted. Not what WebKit does (but its support for setData() is non-existant anyway). IE does this.
The default action of a copy and cut event is to place the selection on the clipboard. Hence, after calling setData() the script must cancel the default action of the event, otherwise the data placed on the clipboard with the setData() call will immediately be overwritten by the default action.
Calling clearData() empties the system clipboard if no argument is given, and removes the specified type of data from the clipboard if called with the optional type argument.
interface ClipboardEvent : Event {
readonly attribute ClipboardData clipboardData;
void initClipboardEvent( in DOMString eventType,
in boolean canBubble,
in boolean cancelable,
in DOMString dataType,
in DOMString data );
};
The ClipboardEvent interface extends the Event interface. [DOMEVENTS]
The clipboardData attribute is an instance of the ClipboardData interface which lets a script read and manipulate values on the system clipboard during user-initiated copy, cut and paste operations.
This method initializes attributes of an Event created through the DocumentEvent.createEvent() method. [DOMEVENTS]. The dataType argument is a MIME type describing the format of the data argument. Event listeners triggered by the synthetic event can get access to the data by calling ClipboardData.getData() with a string which case-insensitively matches the dataType argument.
A synthetic paste event must not give a script access to data on the real system clipboard. Synthetic cut and copy events must not modify data on the system clipboard.
The values below must be supported by all methods that take a type argument. Note that the type argument is always case-insensitive.
Implementations are encouraged to also support text/html for dealing with HTML-formatted data.
If an implementation supports the document.execCommand method and allows calling it with the commands "cut", "copy" and "paste", the implementation must fire the corresponding events. The event is syncronous and may prevent the execCommand() call from having its normal effect.
Untrusted scripts should not get uncontrolled access to a user's clipboard data. This specification assumes that granting access to the current clipboard data when a user explicitly initiates a paste operation from the UA's trusted chrome is acceptable. However, implementors must proceed carefully, and as a minimum implement the precautions below:
Implementations may choose to further limit the functionality provided by the ClipboardData interface. For example, an implementation may allow the user to disable this API, or configure which web sites should be granted access to it.
Scripts may use the ClipboardData API to annoy and confuse users by altering the data on the system clipboard from copy and cut events. This specification does not attempt to prevent such nuisances, though implementations may add additional restrictions.
Implementations must handle scripts that try to place excessive amounts of data on the clipboard gracefully.
How do we safeguard cross-origin copy/paste of HTML source code?
Pasting HTML copied from one site into another site might compromise the security of the former site, for example by giving the second site access to passwords, nonces and other sensitive data that might be embedded in the markup.
If a script calls getData('text/html'), the implementation supports pasting HTML, and the data available on the clipboard is from a different origin, the implementation must sanitize the content by following these steps:
Implementations may implement additional restrictions, for example only support text/plain if the user does a cross-origin paste, or only support text/plain if content from an encrypted origin is pasted into a non-encrypted page.
Is this sufficient to prevent sneaky cross-site request forgery attacks?
Thanks to Anne van Kesteren, Tarquin Wilton-Jones