Skip to content

Instantly share code, notes, and snippets.

@JamesMGreene

JamesMGreene/ZeroClipboard v2 API.md

Last active December 30, 2015 21:19
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save JamesMGreene/7886534 to your computer and use it in GitHub Desktop.
Save JamesMGreene/7886534 to your computer and use it in GitHub Desktop.
Download ZIP
ZeroClipboard v2.0.0 API Draft
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 name property set to "flash-disabled".
    • "wrongFlash" → "error" with name 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