Skip to content

Instantly share code, notes, and snippets.

@wangwen1220

wangwen1220/ZeroClipboard v2 API.md

Forked from JamesMGreene/ZeroClipboard v2 API.md
Created March 6, 2014 14:43
Show Gist options
  • Save wangwen1220/9391245 to your computer and use it in GitHub Desktop.
Save wangwen1220/9391245 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ZeroClipboard v2 API.md

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
};
  • _globalConfig.swfPath
  • _globalConfig.trustedDomains
  • _globalConfig.cacheBust
  • _globalConfig.forceHandCursor
  • _globalConfig.zIndex
  • _globalConfig.title
  • _globalConfig.forceEnhancedClipboard
  • _globalConfig.bubbleEvents
  • _globalConfig.autoActivate

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

  • client.clip(...); ← Replaces client.glue(...);
  • client.unclip(...); ← Replaces client.unglue(...);
  • client.handlers(); ← ("getter") Replaces client's client.handlers property
  • client.handlers("load"); ← ("getter" for a single event type) Replaces client's client.handlers[eventType]
  • client.elements(); → "getter" method that returns array of client's clipped elements
  • client.destroy();
  • client.on(...);
  • client.on({ ... }); → Supports the "events map" concept from jQuery
  • client.off(...);
  • client.off({ ... }); → Supports the "events map" concept from jQuery

Events

  • "ready" ← Formerly "load"; also updating the event data, see gist
  • "beforecopy" and "copy" ← Formerly "dataRequested"
  • "aftercopy" ← Formerly "complete". Fires after the clipboard injection but before the "click" event bubble is dispatched.
  • "error"[name === "flash-disabled"] ← Formerly "noFlash"; Flash is disabled or not installed.
  • "error"[name === "flash-outdated"] ← Formerly "wrongFlash"; 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 SWF and ZeroClipboard JS are different versions; Better name suggestions welcomed!
  • "error"[name === "clipboard-failure"] → Clipboard injection failed or threw an error; Better name suggestions welcomed!
  • "error"[name === (etc.???)] → ???

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

OR:

[C] Instance methods (has parity with the current v1.x API)

  • client.setText("..."); → Shortcut for client.setData({ "text/plain": "..." });
  • client.setHtml("..."); → Shortcut for client.setData({ "text/html": "..." });
  • client.setRichText("..."); → Shortcut for client.setData({ "application/rtf": "..." });
  • client.setData({ ... });, e.g.
client.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**"
});
  • client.clearData("text/html"); → Clears the pending clipboard data for the HTML sector of the clipboard
  • client.clearData(); → Clears the pending clipboard data for all sectors of the clipboard

Upgrade Guide

Renamed but Near-Identical Functionality

  • ZeroClipboard.dispatch(...); → ZeroClipboard.emit(...);
  • ZeroClipboard.setDefaults({ ... }); → ZeroClipboard.config({ ... });
  • client.options.trustedOrigins = []; → ZeroClipboard.config({ trustedDomains: [] });
  • client.options.moviePath = "ZC.swf"; → ZeroClipboard.config({ swfPath: "ZC.swf" });
  • client.options.useNoCache = false; → ZeroClipboard.config({ cacheBust: false });
  • client.handlers → client.handlers(); [CONFUSING CHANGE but the old handlers property wasn't listed in the public API]
  • client.setCurrent(...); → ZeroClipboard.activate(...);
  • client.resetBridge(); → Use ZeroClipboard.deactivate();
  • client.setText(...); → ??? Still up for debate. Use ZeroClipboard.setText(...); ???
  • client.glue(...); → Use client.clip(...);
  • client.unglue(...); → Use client.unclip(...);

Replaced with Similar Functionality

  • Constructor no longer accepts a 2nd argument as per-client config options. Use ZeroClipboard.config(...);.
  • Default value of client.options.trustedDomains: null → [window.location.host]
  • client.options.allowScriptAccess = "always"; → This will be automatically set for you based on the trustedDomains config value
  • client.setTitle(...); → Use ZeroClipboard.config({ title: "My Title" });
  • client.options.hoverClass = "blah"; → You should be able to just use normal CSS :hover selectors
  • client.options.activeClass = "blah"; → You should be able to just use normal CSS :active selectors
  • Events:
    • "load" → "ready"; also updating the event data, see gist
    • "noFlash" → "error" with type property set to "flash-missing".
    • "wrongFlash" → "error" with type property set to "flash-outdated".
    • "dataRequested" → "beforecopy" and "copy"
    • "complete" → "aftercopy"
  • Event handler callback signature and context has changed. See "Event Handler Format" above.

Removed from Public API

Intentionally Public

  • ZeroClipboard.detectFlashSupport();
  • client.options.allowScriptAccess = "always"; → This SWF outbound scripting policy will be set automatically by ZeroClipboard but only if necessary
  • client.options.debug = false; → There won't be any deprecation warnings in v2.0.0, so this option will be at least temporarily unnecessary
  • client.ready(); → No need to expose the state; use client.on("ready", function(e) { /* ... */ });
  • client.addEventListener(...); → Use client.on(...);
  • client.removeEventListener(...); → Use client.off(...);
  • client.reposition();
  • client.setHandCursor(...);
  • client.setSize(...);
  • client.receiveEvent(...);
  • Events:
    • "mouseover"
    • "mouseout"
    • "mousedown"
    • "mouseup"

Internal but Publicly Exposed

  • client.flashBridge
  • client.htmlBridge
  • client.options → Use ZeroClipboard.config();
  • client._singleton
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment