ZeroClipboard v2.0.0 "Core" API Draft

Working draft of the API for the new ZeroClipboard "Core" sub-module in v2.0.0. This sub-module only provides the core Flash and clipboard injection facilities but none of the DOM, "Client", resizing, repositioning, etc. logic/code.

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

API

Configuration

var _coreConfig = {

  // 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,

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

_coreConfig.swfPath
_coreConfig.trustedDomains
_coreConfig.cacheBust
_coreConfig.forceEnhancedClipboard

Static Properties

ZeroClipboard.Core.version

Static Methods

ZeroClipboard.Core.config({ ... }); → (setter)
ZeroClipboard.Core.config(); → (getter)
ZeroClipboard.Core.create(); → Creates the Flash bridge (and its container element)
ZeroClipboard.Core.destroy(); → Destroys the Flash bridge (and its container element)
ZeroClipboard.Core.emit(...); → Dispatch an event to trigger registered event handlers
ZeroClipboard.Core.on({ ... }); → Register an "events map" (see jQuery), a mapping of event types to handlers
ZeroClipboard.Core.off({ ... }); → Unregister an "events map" (see jQuery), a mapping of event types to handlers
ZeroClipboard.Core.state() → Diagnostic; returns an object describing the state of the browser, Flash Player, and ZeroClipboard "Core"

Events

Event Handler Format

Aligns with DOM event standards for an event data object:

ZeroClipboard.Core.on("ready", function(e) {
  // `this` === `???`
  // `e.type` === `"ready"`
  // `e.target` === `flashState.bridge || null`
  // `e.{whatever}` === whatever else (data, args, etc.)
});

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

var obj = {
  foo: "bar",
  handleEvent: function(e) {
    // `this` === `obj`
    // `e.type` === `"ready"`
    // `e.target` === `flashState.bridge || null`
    // `e.{whatever}` === whatever else (data, args, etc.)
  }
};
client.on("ready", obj);

Clipboard Injection

Active Injection

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.

ZeroClipboard.Core.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:

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

ZeroClipboard.Core.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.Core.clearData("text/html"); → Clears the pending clipboard data for the HTML sector of the clipboard
ZeroClipboard.Core.clearData(); → Clears the pending clipboard data for all sectors of the clipboard

JamesMGreene/ZeroClipboard "Core" v2 API.md