Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
ZeroClipboard "Core" v2.0.0 API

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.)
});
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.