ZeroClipboard "Core" v2.0.0 API

ZeroClipboard "Core" v2 API.md

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

• "ready" → The Flash movie is loaded and ready
• "beforecopy" → The user has clicked and the clipboard injection process is about to begin. Use this if you need to make UI adjustments ahead of time.
• "copy" →
• "aftercopy" → The clipboard injection process completed successfully. Consumers should also listen to "error"[name === "clipboard-failure"] (see below) if you want to know when the process failed.
• "error"[name === "flash-disabled"] → Flash is disabled or not installed.
• "error"[name === "flash-outdated"] → Flash is too old for ZeroClipboard
• "error"[name === "flash-deactivated"] → Flash is too old for your browser and/or is currently "click-to-play"
• "error"[name === "flash-unavailable"] → ExternalInterface.available returns false, so we cannot communicate from JS to Flash
• "error"[name === "version-mismatch"] → ZeroClipboard "Core" SWF and ZeroClipboard "Core" JS are different versions; Better name suggestions welcomed!
• "error"[name === "clipboard-failure"] → Clipboard injection failed or threw an error; Better name suggestions welcomed!

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