# ZeroClipboard API
This documents details the ZeroClipboard API, including various types of properties, methods, and events.
## Static
### Static Properties
#### `ZeroClipboard.version`
_[`String`]_ The version of the ZeroClipboard library being used, e.g. `"2.0.0"`.
### Static Methods
#### `ZeroClipboard.config(...)`
```js
var config = ZeroClipboard.config();
```
_[`Object`]_ Get a copy of the active configuration for ZeroClipboard.
```js
var swfPath = ZeroClipboard.config("swfPath");
```
_[`*`]_ Get a copy of the actively configured value for this configuration property for ZeroClipboard.
```js
var config = ZeroClipboard.config({
forceHandCursor: true
});
```
_[`Object`]_ Set the active configuration for ZeroClipboard. Returns a copy of the updated active configuration. For complete details about what can be configured, see [**Configuration Options** below](#configuration-options).
#### `ZeroClipboard.create()`
_[`undefined`]_ Create the Flash bridge SWF object. _**IMPORTANT:**_ This method should be considered private.
#### `ZeroClipboard.destroy()`
_[`undefined`]_ Emit the [`"destroy"`](#destroy) event, remove all event handlers, and destroy the Flash bridge.
#### `ZeroClipboard.setData(...)`
```js
ZeroClipboard.setData("text/plain", "Blah");
```
_[`undefined`]_ Set the pending `data` of type `format` for clipboard injection.
```js
ZeroClipboard.setData({
"text/plain": "Blah",
"text/html": "Blah"
});
```
_[`undefined`]_ Set the pending `data` of various formats for clipboard injection.
#### `ZeroClipboard.clearData(...)`
```js
ZeroClipboard.clearData("text/plain");
```
_[`undefined`]_ Clear the pending data of type `format` for clipboard injection.
```js
ZeroClipboard.clearData();
```
_[`undefined`]_ Clear the pending data of ALL formats for clipboard injection.
#### `ZeroClipboard.getData(...)`
```js
var text = ZeroClipboard.getData("text/plain");
```
_[`String`]_ Get the pending data of type `format` for clipboard injection.
```js
var dataObj = ZeroClipboard.getData();
```
_[`Object`]_ Get a copy of the pending data of ALL formats for clipboard injection.
#### `ZeroClipboard.focus(...)`
#### `ZeroClipboard.activate(...)`
```js
ZeroClipboard.focus(document.getElementById("d_clip_button"));
```
_[`undefined`]_ Focus/"activate" the provided element by moving the Flash SWF object in front of it. **NOTE:** The preferred method to use is `focus` but the alias `activate` is available for backward compatibility's sake.
#### `ZeroClipboard.blur()`
#### `ZeroClipboard.deactivate()`
_[`undefined`]_ Blur/"deactivate" the currently focused/"activated" element, moving the Flash SWF object off the screen. **NOTE:** The preferred method to use is `blur` but the alias `deactivate` is available for backward compatibility's sake.
#### `ZeroClipboard.activeElement()`
```js
var el = document.getElementById("d_clip_button");
ZeroClipboard.focus(el);
var activeEl = ZeroClipboard.activeElement(); // activeEl === el
```
_[`HTMLElement` or `null`]_ Return the currently "activated" element that the Flash SWF object is in front of it.
#### `ZeroClipboard.state()`
_[`Object`]_ Diagnostic method that describes the state of the browser, Flash Player, and ZeroClipboard.
#### `ZeroClipboard.isFlashUnavailable()`
_[`Boolean`]_ Indicates if Flash Player is **definitely** unusable (disabled, outdated, unavailable, or deactivated). _**IMPORTANT:**_ This method should be considered private.
#### `ZeroClipboard.on(...)`
```js
var listenerFn = function(e) { var ZeroClipboard = this; /* ... */ };
ZeroClipboard.on("ready", listenerFn);
var listenerObj = {
handleEvent: function(e) { var listenerObj = this; /* ... */ }
};
ZeroClipboard.on("error", listenerObj);
```
_[`undefined`]_ Add a `listener` function/object for an `eventType`.
```js
ZeroClipboard.on("ready error", function(e) { /* ... */ });
```
_[`undefined`]_ Add a `listener` function/object for multiple `eventType`s.
```js
ZeroClipboard.on({
"ready": function(e) { /* ... */ },
"error": function(e) { /* ... */ }
});
```
_[`undefined`]_ Add a set of `eventType` to `listener` function/object mappings.
#### `ZeroClipboard.off(...)`
```js
ZeroClipboard.off("ready", listenerFn);
ZeroClipboard.off("error", listenerObj);
```
_[`undefined`]_ Remove a `listener` function/object for an `eventType`.
```js
ZeroClipboard.off("ready error", listenerFn);
```
_[`undefined`]_ Remove a `listener` function/object for multiple `eventType`s.
```js
ZeroClipboard.off({
"ready": readyListenerFn,
"error": errorListenerFn
});
```
_[`undefined`]_ Remove a set of `eventType` to `listener` function/object mappings.
```js
ZeroClipboard.off("ready");
```
_[`undefined`]_ Remove ALL listener functions/objects for an `eventType`.
```js
ZeroClipboard.off();
```
_[`undefined`]_ Remove ALL listener functions/objects for ALL registered event types.
#### `ZeroClipboard.emit(...)`
```js
ZeroClipboard.emit("ready");
ZeroClipboard.emit({
type: "error",
name: "flash-disabled"
});
var pendingCopyData = ZeroClipboard.emit("copy");
```
_[`undefined`, or a Flash-friendly data `Object` for the `"copy"` event]_ Dispatch an event to all
registered listeners. The emission of some types of events will result in side effects.
#### `ZeroClipboard.handlers(...)`
```js
var listeners = ZeroClipboard.handlers("ready");
```
_[`Array`]_ Retrieves a copy of the registered listener functions/objects for the given `eventType`.
```js
var listeners = ZeroClipboard.handlers();
```
_[`Object`]_ Retrieves a copy of the map of registered listener functions/objects for ALL event types.
### Static Events
#### `"ready"`
The `ready` event is fired when the Flash SWF completes loading and is ready for action. Please
note that you need to set most configuration options [with [`ZeroClipboard.config(...)`](#zeroclipboardconfig)]
before `ZeroClipboard.create()` is invoked.
```js
ZeroClipboard.on("ready", function(e) {
/*
e = {
type: "ready",
message: "Flash communication is established",
target: null,
relatedTarget: null,
currentTarget: flashSwfObjectRef,
version: "11.2.202",
timeStamp: Date.now()
};
*/
});
```
#### `"beforecopy"`
On `click`, the Flash object will fire off a `beforecopy` event. This event is generally only
used for "UI prepartion" if you want to alter anything before the `copy` event fires.
**IMPORTANT:** Handlers of this event are expected to operate synchronously if they intend to be
finished before the "copy" event is triggered.
```js
ZeroClipboard.on("beforecopy", function(e) {
/*
e = {
type: "beforecopy",
target: currentlyActivatedElementOrNull,
relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now()
};
*/
});
```
#### `"copy"`
On `click` (and after the `beforecopy` event), the Flash object will fire off a `copy` event. If
the HTML object has `data-clipboard-text` or `data-clipboard-target`, then ZeroClipboard will take
care of getting an initial set of data. It will then invoke any `copy` event handlers, in which you
can call `event.clipboardData.setData` to set the text, which will complete the loop.
**IMPORTANT:** If a handler of this event intends to modify the pending data for clipboard
injection, it _MUST_ operate synchronously in order to maintain the temporarily elevated
permissions granted by the user's `click` event. The most common "gotcha" for this restriction is
if someone wants to make an asynchronous XMLHttpRequest in response to the `copy` event to get the
data to inject — this won't work; make it a _synchronous_ XMLHttpRequest instead, or do the
work in advance before the `copy` event is fired.
```js
ZeroClipboard.on("copy", function(e) {
/*
e = {
type: "copy",
target: currentlyActivatedElementOrNull,
relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
clipboardData: {
setData: ZeroClipboard.setData,
clearData: ZeroClipboard.clearData
}
};
*/
});
```
#### `"aftercopy"`
The `aftercopy` event is fired when the text is copied [or failed to copy] to the clipboard.
```js
ZeroClipboard.on("aftercopy", function(e) {
/*
e = {
type: "aftercopy",
target: currentlyActivatedElementOrNull,
relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
success: {
"text/plain": true,
"text/html": true,
"application/rtf": false
},
data: {
"text/plain": "Blah",
"text/html": "Blah",
"application/rtf": "{\\rtf1\\ansi\n{\\b Blah}}"
}
};
*/
});
```
#### `"destroy"`
The `destroy` event is fired when `ZeroClipboard.destroy()` is invoked.
**IMPORTANT:** Handlers of this event are expected to operate synchronously if they intend to be
finished before the destruction is complete.
```js
ZeroClipboard.on("destroy", function(e) {
/*
e = {
type: "destroy",
target: null,
relatedTarget: null,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
success: {
"text/plain": true,
"text/html": true,
"application/rtf": false
},
data: {
"text/plain": "Blah",
"text/html": "Blah",
"application/rtf": "{\\rtf1\\ansi\n{\\b Blah}}"
}
};
*/
});
```
#### `"error"`
The `error` event is fired under a number of conditions, which will be detailed as sub-sections below.
Some consumers may not consider all `error` types to be critical, and thus ZeroClipboard does not take it upon
itself to implode by calling `ZeroClipboard.destroy()` under error conditions. However, many consumers may
want to do just that.
##### `error[name = "flash-disabled"]`
This type of `error` event fires when Flash Player is either not installed or not enabled in the browser.
```js
ZeroClipboard.on("error", function(e) {
/*
e = {
type: "error",
name: "flash-disabled",
messsage: "Flash is disabled or not installed",
target: null,
relatedTarget: null,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
minimumVersion: "11.0.0"
};
*/
});
```
##### `error[name = "flash-outdated"]`
This type of `error` event fires when Flash Player is installed in the browser but the version is too old
for ZeroClipboard. ZeroClipboard requires Flash Player 11.0.0 or above.
```js
ZeroClipboard.on("error", function(e) {
/*
e = {
type: "error",
name: "flash-outdated",
messsage: "Flash is too outdated to support ZeroClipboard",
target: null,
relatedTarget: null,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
minimumVersion: "11.0.0",
version: "10.3.183"
};
*/
});
```
##### `error[name = "flash-unavailable"]`
This type of `error` event fires when the browser's installation of Flash Player cannot communicate bidirectionally with JavaScript.
```js
ZeroClipboard.on("error", function(e) {
/*
e = {
type: "error",
name: "flash-unavailable",
messsage: "Flash is unable to communicate bidirectionally with JavaScript",
target: null,
relatedTarget: null,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
minimumVersion: "11.0.0",
version: "11.2.202"
};
*/
});
```
##### `error[name = "flash-deactivated"]`
This type of `error` event fires when the browser's installation of Flash Player is either too old
for the browser [but _not_ too old for ZeroClipboard] or if Flash objects are configured as
click-to-play and the user does not authorize it within `_globalConfig.flashLoadTimeout`
milliseconds or does not authorize it at all.
```js
ZeroClipboard.on("error", function(e) {
/*
e = {
type: "error",
name: "flash-deactivated",
messsage: "Flash is too outdated for your browser and/or is configured as click-to-activate",
target: null,
relatedTarget: null,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
minimumVersion: "11.0.0",
version: "11.2.202"
};
*/
});
```
##### `error[name = "flash-overdue"]`
This type of `error` event fires when the SWF loads successfully but takes longer than
`_globalConfig.flashLoadTimeout` milliseconds to do so. This would likely be caused by
one of the following situations:
1. Too short of a `_globalConfig.flashLoadTimeout` duration configured
2. Network latency
3. The user's installation of Flash is configured as click-to-play but then authorized
by the user too late such that the SWF does not finish loading before the timeout
period has expired (or it may have expired before they authorized it at all).
The appropriate response to this event is left up to the consumer. For instance, if they
chose to invoke `ZeroClipboard.destroy()` in response to the earlier
`error[name = "flash-deactivated"]` event but then receive this `error[name = "flash-overdue"]`
event, they may choose to "restart" their process and construct new ZeroClipboard client instances,
or they may choose to just log the error to their server so they can consider increasing the
allowed timeout duration in the future.
This may be especially important for SPA or PJAX-based applications to consider as their users
may remain on a single page for an extended period of time during which they _possibly_ could
have enjoyed an improved experience if ZeroClipboard had been "restarted" after an initial hiccup.
```js
ZeroClipboard.on("error", function(e) {
/*
e = {
type: "error",
name: "flash-overdue",
messsage: "Flash communication was established but NOT within the acceptable time limit",
target: null,
relatedTarget: null,
currentTarget: flashSwfObjectRef,
timeStamp: Date.now(),
minimumVersion: "11.0.0",
version: "11.2.202"
};
*/
});
```
## Instance
The following properties and methods are accessible via a `ZeroClipboard` client instance, e.g.
```js
var clippedEl = document.getElementById("d_clip_button");
var client = new ZeroClipboard(clippedEl);
```
### Instance Properties
#### `client.id`
_[`String`]_ A unique identifier for this ZeroClipboard client instance.
### Instance Methods
#### `client.destroy()`
_[`undefined`]_ Remove all event handlers and unclip all clipped elements.
#### `client.setText(...)`
```js
client.setText("Blah");
```
_[`this`]_ Set the pending `data` of type `"text/plain"` for clipboard injection.
#### `client.setHtml(...)`
```js
client.setHtml("Blah");
```
_[`this`]_ Set the pending `data` of type `"text/html"` for clipboard injection.
#### `client.setRichText(...)`
```js
client.setRichText("{\\rtf1\\ansi\n{\\b Blah}}");
```
_[`this`]_ Set the pending `data` of type `"application/rtf"` for clipboard injection.
#### `client.setData(...)`
```js
client.setData("text/plain", "Blah");
```
_[`this`]_ Set the pending `data` of type `format` for clipboard injection.
```js
client.setData({
"text/plain": "Blah",
"text/html": "Blah"
});
```
_[`this`]_ Set the pending `data` of various formats for clipboard injection. This particular
function signature (passing in an `Object`) will implicitly clear out any existing pending data.
#### `client.clearData(...)`
```js
client.clearData("text/plain");
```
_[`this`]_ Clear the pending data of type `format` for clipboard injection.
```js
client.clearData();
```
_[`this`]_ Clear the pending data of ALL formats for clipboard injection.
#### `client.getData(...)`
```js
var text = client.getData("text/plain");
```
_[`String`]_ Get the pending data of type `format` for clipboard injection.
```js
var dataObj = client.getData();
```
_[`Object`]_ Get a copy of the pending data of ALL formats for clipboard injection.
#### `client.clip(...)`
```js
client.clip(document.getElementById("d_clip_button"))
client.clip(document.querySelectorAll(".clip_button"));
client.clip(jQuery(".clip_button"));
```
_[`this`]_ Register clipboard actions for new element(s) to the client. This includes
automatically invoking `ZeroClipboard.focus` on the current element when it is hovered over,
unless the `autoActivate` configuration property is set to `false`.
#### `client.unclip(...)`
```js
client.unclip(document.getElementById("d_clip_button"))
client.unclip(document.querySelectorAll(".clip_button"));
client.unclip(jQuery(".clip_button"));
client.unclip();
```
_[`this`]_ Unregister the clipboard actions of previously registered element(s) on the page.
If no elements are provided, ALL clipped/registered elements will be unregistered.
#### `client.elements()`
```js
var els = client.elements();
```
_[`Array`]_ Get all of the elements to which this client is clipped/registered.
#### `client.on(...)`
```js
var listenerFn = function(e) { var client = this; /* ... */ };
client.on("ready", listenerFn);
var listenerObj = {
handleEvent: function(e) { var listenerObj = this; /* ... */ }
};
client.on("error", listenerObj);
```
_[`this`]_ Add a `listener` function/object for an `eventType` within this client instance.
```js
client.on("ready error", function(e) { /* ... */ });
```
_[`this`]_ Add a `listener` function/object for multiple `eventType`s within this client instance.
```js
client.on({
"ready": function(e) { /* ... */ },
"error": function(e) { /* ... */ }
});
```
_[`this`]_ Add a set of `eventType` to `listener` function/object mappings within this client instance.
#### `client.off(...)`
```js
client.off("ready", listenerFn);
client.off("error", listenerObj);
```
_[`this`]_ Remove a `listener` function/object for an `eventType` within this client instance.
```js
client.off("ready error", listenerFn);
```
_[`this`]_ Remove a `listener` function/object for multiple `eventType`s within this client instance.
```js
client.off({
"ready": readyListenerFn,
"error": errorListenerFn
});
```
_[`this`]_ Remove a set of `eventType` to `listener` function/object mappings within this client instance.
```js
client.off("ready");
```
_[`this`]_ Remove ALL listener functions/objects for an `eventType` within this client instance.
```js
client.off();
```
_[`this`]_ Remove ALL listener functions/objects for ALL registered event types within this client instance.
#### `client.emit(...)`
```js
client.emit("ready");
client.emit({
type: "error",
name: "flash-disabled"
});
```
_[`undefined`]_ Dispatch an event to all registered listeners within this client instance.
#### `client.handlers(...)`
```js
var listeners = client.handlers("ready");
```
_[`Array`]_ Retrieves a copy of the registered listener functions/objects for the given `eventType` within this client instance.
```js
var listeners = client.handlers();
```
_[`Object`]_ Retrieves a copy of the map of registered listener functions/objects for ALL event types within this client instance.
### Instance Events
See the [Static Events](#static-events) listing. The ZeroClipboard client instances regurgitate the `ZeroClipboard.Core` events, ONLY if the event is NOT impertinent to this particular client. The only difference is that the clients' event dispatching will update the `event` object to include a `client` property that references the relevant client instance, e.g.:
```js
var client = new ZeroClipboard();
client.on("ready", function(e) {
if (e.client === client && client === this) {
console.log("This client instance is ready!");
}
});
```
## Configuration Options
These are default values for the global configurations options. You should generally update these _before_ you create your clients.
```js
var _globalConfig = {
// SWF URL, relative to the page. Default value will be "ZeroClipboard.swf"
// under the same path as the ZeroClipboard JS file.
swfPath: _swfPath,
// SWF inbound scripting policy: page domains that the SWF should trust.
// (single string, or array of strings)
trustedDomains: window.location.host ? [window.location.host] : [],
// Include a "noCache" query parameter on requests for the SWF.
cacheBust: true,
// Enable use of the fancy "Desktop" clipboard, even on Linux where it is
// known to suck.
forceEnhancedClipboard: false,
// How many milliseconds to wait for the Flash SWF to load and respond before assuming that
// Flash is deactivated (e.g. click-to-play) in the user's browser. If you don't care about
// how long it takes to load the SWF, you can set this to `null`.
flashLoadTimeout: 30000,
// Setting this to `false` would allow users to handle calling `ZeroClipboard.focus(...);`
// themselves instead of relying on our per-element `mouseover` handler.
autoActivate: true,
// Bubble synthetic events in JavaScript after they are received by the Flash object.
bubbleEvents: true,
// Sets the ID of the `div` encapsulating the Flash object.
// Value is validated against the [HTML4 spec for `ID` tokens][valid_ids].
containerId: "global-zeroclipboard-html-bridge",
// Sets the class of the `div` encapsulating the Flash object.
containerClass: "global-zeroclipboard-container",
// Sets the ID and name of the Flash `object` element.
// Value is validated against the [HTML4 spec for `ID` and `Name` tokens][valid_ids].
swfObjectId: "global-zeroclipboard-flash-bridge",
// The class used to indicate that a clipped element is being hovered over.
hoverClass: "zeroclipboard-is-hover",
// The class used to indicate that a clipped element is active (is being clicked).
activeClass: "zeroclipboard-is-active",
// Forcibly set the hand cursor ("pointer") for all clipped elements.
// IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded.
forceHandCursor: false,
// Sets the title of the `div` encapsulating the Flash object.
// IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded.
title: null,
// The z-index used by the Flash object.
// Max value (32-bit): 2147483647.
// IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded.
zIndex: 999999999
};
```
You can override the defaults by making calls like `ZeroClipboard.config({ swfPath: "new/path" });`
before you create any clients.
### SWF Inbound Scripting Access: The `trustedDomains` option
This allows other SWF files and HTML pages from the allowed domains to access/call publicly
exposed ActionScript code, e.g. functions shared via `ExternalInterface.addCallback`. In other
words, it controls the SWF inbound scripting access.
If your ZeroClipboard SWF is served from a different origin/domain than your page, you need to tell
the SWF that it's OK to trust your page. The default value of `[window.location.host]` is almost
_**always**_ what you will want unless you specifically want the SWF to communicate with pages from
other domains (e.g. in `iframe`s or child windows).
For more information about trusted domains, consult the [_official Flash documentation for `flash.system.Security.allowDomain(...)`_](http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/system/Security.html#allowDomain\(\)).
### SWF Outbound Scripting Access
The `allowScriptAccess` parameter (for Flash embedding markup) allows the SWF file to access/call
JavaScript/HTML functionality of HTML pages on allowed domains, e.g. invoking functions via
`ExternalInterface.call`. In other words, it controls the SWF outbound scripting access.
As of version `v2.0.0-alpha.2`, the `allowScriptAccess` configuration option no longer exists. The
appropriate value will be determined immediately before the Flash object is embedded on the page.
The value is based on a relationship between the current domain (`window.location.host`) and the
value of the `trustedDomains` configuration option.
For more information about `allowScriptAccess`, consult the [_official Flash documentation_](http://helpx.adobe.com/flash/kb/control-access-scripts-host-web.html).
### Cross-Protocol Limitations
ZeroClipboard was intentionally configured to _not_ allow the SWF to be served from a secure domain (HTTPS) but scripted by an insecure domain (HTTP).
If you find yourself in this situation (as in [Issue #170](https://github.com/zeroclipboard/zeroclipboard/issues/170)), please consider the following options:
1. Serve the SWF over HTTP instead of HTTPS. If the page's protocol can vary (e.g. authorized/unauthorized, staging/production, etc.), you should include add the SWF with a relative protocol (`//s3.amazonaws.com/blah/ZeroClipboard.swf`) instead of an absolute protocol (`https://s3.amazonaws.com/blah/ZeroClipboard.swf`).
2. Serve the page over HTTPS instead of HTTP. If the page's protocol can vary, see the note on the previous option (1).
3. Update ZeroClipboard's ActionScript codebase to call the [`allowInsecureDomain`](http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/system/Security.html#allowInsecureDomain\(\)) method, then recompile the SWF with your custom changes.
### `file://` Protocol Limitations
If you want to host a page locally on the `file://` protocol, you must specifically configure
ZeroClipboard to trust ALL domains for SWF interaction via a wildcard. This configuration must be
set _before_ creating ZeroClipboard client instances as a typical consumer, or before calling
`ZeroClipboard.create()` in a 3rd party wrapper:
```js
ZeroClipboard.config({ trustedDomains: ["*"] });
```
This wildcard configuration should _**NOT**_ be used in environments hosted over HTTP/HTTPS.