ZeroClipboard v2.0.0 API Draft

Working draft of the new API for ZeroClipboard v2.0.0.

NOTE: A checked checkbox means that line item has already been implemented in the latest ZeroClipboard master branch.

API

Global Configuration

var _globalConfig = {

  // URL to movie, relative to the page. Default value will be "ZeroClipboard.swf" under the
  // same path as the ZeroClipboard JS file.
  swfPath: "path/to/ZeroClipboard.swf",

  // Page domains that the SWF should trust (single string or array of strings)
  trustedDomains: [window.location.host],

  // Include a "nocache" query parameter on requests for the SWF
  cacheBust: true,

  // Forcibly set the hand cursor ("pointer") for all clipped elements
  forceHandCursor: false,

  // The z-index used by the Flash object. Max value (32-bit): 2147483647
  zIndex: 999999999,


  //
  // NEW OPTIONS
  //

  // Sets the title of the `div` encapsulating the Flash object
  title: null,

  // Force the use of the enhanced (rich) clipboard on Linux OSes despite its problems
  forceEnhancedClipboard: false,

  // Have Flash object re-dispatch events that it swallows (`click`, etc.)
  bubbleEvents: true,

  // Setting this to `false` would allow users to handle calling `ZeroClipboard.activate(...);`
  // themselves instead of relying on our per-element `mouseover` handler
  autoActivate: true
};

Static Properties

ZeroClipboard.version

Static Methods

ZeroClipboard.config({ ... }); (setter) ← Replaces ZeroClipboard.setDefaults({ ... });
ZeroClipboard.config(); (getter)
ZeroClipboard.config("swfPath"); (getter for a single option)
ZeroClipboard.destroy(); → Destroys all ZeroClipboard instances and the Flash bridge
ZeroClipboard.emit(...); ← Replaces ZeroClipboard.dispatch(...);
ZeroClipboard.activate(...); ← Replaces client.setCurrent(...);
ZeroClipboard.deactivate(); ← Replaces client.resetBridge();
ZeroClipboard.state() → Diagnostic; returns a JSON object describing the state of the browser, Flash Player, and ZeroClipboard

Instance Constructor

No per-client config options

function ZeroClipboard(elementsToClip  /* no longer accept config options here */) {
  /* ... */
}

/* no elements */
var clip1 = new ZeroClipboard();
/* single element */
var clip2 = new ZeroClipboard(document.getElementById("d_clip_button"));
/* list of elements */
var clip3 = new ZeroClipboard($(".clipboard"));

Instance Properties

client.id

Instance Methods

Events

Event Handler Format

Updated to align with DOM event standards for an event data object:

client.on("x", function(e) {
  // `this` === `client`
  // `e.client` === `client`
  // `e.target` === clipped element or `null`
  // `e.type` === `"x"`
  // `e.{whatever}` === whatever else (args)
});

Also include support for objects implementing the EventListener interface (i.e. objects with a handleEvent function):

var obj = {
  foo: "bar",
  handleEvent: function(e) {
    // `this` === `obj`
    // `e.client` === `client`
    // `e.target` === clipped element or `null`
    // `e.type` === `"x"`
    // `e.{whatever}` === whatever else (args)
  }
};
client.on("x", obj);

Clipboard Injection

Passive Injection

Continue to offer passive injection via data-clipboard-text and data-clipboard-target attributes. Should this be controlled via configuration rather than always on?
??? If no data-clipboard-text or data-clipboard-target attributes are specified and there isn't any copy event handler, can still offer a passive copy on the currently selected text. Is this desirable? Should it be controlled via configuration (default → on) rather than via the mentioned rules?

Active Injection

Which one(s)???

In the spirit of the HTML5 Clipboard API. Definitely including this one BUT... should a call to e.preventDefault(); be required like it is in the HTML Clipboard API? During copy event callbacks, e.g.

client.on("copy", function(e) {
  e.clipboardData.clearData();
  e.clipboardData.setData("text/plain", "...");
  // NOTE: The following method taking an object/hash/map as an argument is NOT part of the
  //       HTML Clipboard API
  e.clipboardData.setData({
    "text/plain": "...",
    "text/html":  "<i>...</i>"
  });
  // NOTE: The following call is REQUIRED in the HTML Clipboard API due to IE backwards
  //       compatibility but we could choose to go either way
  e.preventDefault();
});

AND:

[A] No other active methods.

OR:

[B] Static methods (which is more truthful to how it works given there is only one shared Flash object):

ZeroClipboard.setText("..."); → Shortcut for ZeroClipboard.setData({ "text/plain": "..." });
ZeroClipboard.setHtml("..."); → Shortcut for ZeroClipboard.setData({ "text/html": "..." });
ZeroClipboard.setRichText("..."); → Shortcut for ZeroClipboard.setData({ "application/rtf": "..." });
ZeroClipboard.setData({ ... });, e.g.

ZeroClipboard.setData({
  /* Three standard data types */
  "text/plain": "Zero",
  "text/html": "<b>Zero</b>",
  "application/rtf": "{\\rtf1\\ansi\n{\\b Zero}}",

  /* Custom formats that must have a receiver listening for a paste from this clipboard sector */
  "text/x-markdown": "**Zero**"
});

ZeroClipboard.clearData("text/html"); → Clears the pending clipboard data for the HTML sector of the clipboard
ZeroClipboard.clearData(); → Clears the pending clipboard data for all sectors of the clipboard