Instructions

Featured

Updated Mar 14, 2010 by jhuck...@gmail.com

Overview
Usage

Setup
Clients
Setting Options
Gluing
Page Resizing
Hiding and Showing
Custom Implementation
Event Handlers

Examples

Minimal Example
Complete Example

Browser Support

Overview

The Zero Clipboard JavaScript library provides an easy way to copy text to the clipboard using an invisible Adobe Flash movie. The "Zero" signifies that the library is invisible and the user interface is left entirely up to you.

This library is fully compatible with Flash Player 10, which requires that the copy operation initiated by a user click event inside the Flash movie. This is achieved by automatically floating the invisible movie on top of a DOM element of your choice. Standard mouse events are even propagated out to your DOM element, so you can still have rollover and mouse down effects.

Flash Player 9 is also supported. Please note that if you use the new Rich HTML feature, your users must have Flash Player 10. There is no automatic fallback to the Flash 9 movie.

Usage

The following subsections describe how to use the clipboard library.

Setup

To use the library, simply include the following JavaScript file in your page:

	<script type="text/javascript" src="ZeroClipboard.js"></script>

You also need to have the "ZeroClipboard.swf" file available to the browser. If this file is located in the same directory as your web page, then it will work out of the box. However, if the SWF file is hosted elsewhere, you need to set the URL like this (place this code after the script tag):

	ZeroClipboard.setMoviePath( 'http://YOURSERVER/path/ZeroClipboard.swf' );

To use the new Rich HTML feature available in Zero Clipboard 1.0.7, you must set the movie path to the new "ZeroClipboard10.swf" file, which is included in the 1.0.7 archive. Example:

	ZeroClipboard.setMoviePath( 'ZeroClipboard10.swf' );

Or, in a custom location other than the current directory:

	ZeroClipboard.setMoviePath( 'http://YOURSERVER/path/ZeroClipboard10.swf' );

Clients

Now you are ready to create one or more Clients. A client is a single instance of the clipboard library on the page, linked to a particular button or other DOM element. You probably only need a single instance, but if you have multiple copy-to-clipboard buttons on your page, potentially containing different text, you can activate an instance for each. Here is how to create a client instance:

	var clip = new ZeroClipboard.Client();

Next, you can set some options.

Setting Options

Once you have your client instance, you can set some options. These include setting the initial text to be copied, amongst other things. The following subsections describe all the available options you can set.

Text To Copy

This function allows you to set the text to be copied to the clipboard, once the user clicks on the control. You can call this function at any time; when the page first loads, or later in an onMouseOver or onMouseDown handler. Example:

	clip.setText( "Copy me!" );

Hand Cursor

This setting controls whether the "hand" or "arrow" cursor is shown when the mouse hovers over the Flash movie. Here is an example:

	clip.setHandCursor( true );

The only values accepted are true (show "hand" cursor), or false (show "arrow" cursor). The default is true. You can set this option at any time.

Gluing

Gluing refers to the process of "linking" the Flash movie to a DOM element on the page. Meaning, the library will automatically generate a movie that is the exact size of the DOM element, and float it just above the element. Since the Flash movie is completely transparent, the user sees nothing out of the ordinary.

The Flash movie receives the click event and copies the current text (last set with setText()) to the clipboard (a requirement of Flash Player 10 is that a user click event inside the movie must initiate the thread that interacts with the clipboard). Also, mouse actions like hovering and mouse-down generate events that you can capture (see Event Handlers below) and set CSS classes on your DOM element too (see CSS Effects below).

Here is how to glue your clip library instance to a DOM element:

	clip.glue( 'd_clip_button' );

You can pass in a DOM element ID (as shown above), or a reference to the actual DOM element object itself. The rest all happens automatically -- the movie is created, all your options set, and it is floated above the element, awaiting clicks from the user.

The glue system is an optional implementation. If you would prefer to handle your own implementation of the Flash movie, see Custom Implementation below.

Recommended Implementation

It is highly recommended you create a "container" DIV element around your button, set its CSS "position" to "relative", and place your button just inside. Then, pass two arguments to glue(), your button DOM element or ID, and the container DOM element or ID. This way Zero Clipboard can position the floating Flash movie relative to the container DIV (not the page body), resulting in much more exact positioning. Example (HTML):

<div id="d_clip_container" style="position:relative">
   <div id="d_clip_button">Copy to Clipboard</div>
</div>

And the code:

	clip.glue( 'd_clip_button', 'd_clip_container' );

Note that gluing to a container element does not work with the reposition() method (see next section).

Page Resizing

If the page gets resized, or something happens which moves your DOM element, you will need to reposition the movie. This can be achieved by calling the reposition() method. Example:

	clip.reposition();

A typical use of this is to put it inside a window.onresize handler.

If for some reason your DOM element was destroyed and recreated, you can pass the new ID or DOM element reference to the reposition() method. However please note that the new element must be the same size as the previous element. The library does not (yet) support elements that change size.

Note that repositioning only works if you glue using a single argument. If you glue to a parent container element, you cannot (and probably won't ever need to) call reposition().

Hiding and Showing

You can also show and hide the Flash movie on demand, if you have an AJAX web app that dynamically changes content, potentially obscuring the clipboard button. Examples:

	clip.hide();
	clip.show();

The show() function also calls reposition().

CSS Effects

Since the Flash movie is floating on top of your DOM element, it will receive all the mouse events before the browser has a chance to catch them. However, for convenience these events are passed through to your clipboard client which you can capture (see Event Handlers below). But in addition to this, the Flash movie can also activate CSS classes on your DOM element to simulate the ":hover" and ":active" pseudo-classes.

If this feature is enabled, the CSS classes "hover" and "active" are added / removed to your DOM element as the mouse hovers over and clicks the Flash movie. This essentially allows your button to behave normally, even though the floating Flash movie is receiving all the mouse events. Please note that the actual CSS pseudo-classes ":hover" and ":active" are not used -- these cannot be programmatically activated with current browser software. Instead, sub-classes named "hover" and "active" are used. Example CSS:

	#d_clip_button {
		width:150px; 
		text-align:center; 
		border:1px solid black; 
		background-color:#ccc; 
		margin:10px; padding:10px; 
	}
	#d_clip_button.hover { background-color:#eee; }
	#d_clip_button.active { background-color:#aaa; }

These classes are for a DOM element with an ID: "d_clip_button". The "hover" and "active" sub-classes would automatically be activated as the user hovers over, and clicks down on the Flash movie, respectively. They behave exactly like CSS pseudo-classes of the same names.

The CSS Effect system is enabled by default. To disable it, pass false to the setCSSEffects() method. Example:

	clip.setCSSEffects( false );

You can set this option at any time.

Custom Implementation

If you would prefer to instantiate the Flash movie yourself, and completely disable the entire glue and CSS systems, you can simply call the getHTML() method, which returns the actual OBJECT/EMBED tag for the Flash movie. Example:

	var html = clip.getHTML( 150, 20 );

The method requires that you pass in the desired pixel width and height of the movie. The returned HTML can then be inserted into a DOM element of your choice, or written to the page with document.write().

Note: Microsoft Internet Explorer seems to have a bug where the Flash External Interface (the communication layer between JavaScript and Flash) doesn't activate properly unless you insert the OBJECT tag into an element that is already appended to the DOM. So make sure you call appendChild() before you insert the HTML into the innerHTML property of your element.

Event Handlers

The clipboard library allows you set a number of different event handlers. These are all set by calling the addEventListener() method, as in this example:

	clip.addEventListener( 'onLoad', my_load_handler );

The first argument is the name of the event, and the second is a reference to your function. The function may be passed by name (string), an actual reference to the function object, or a PHP-style object/method array:

	clip.addEventListener( 'onMouseDown', [myObject, 'myMethod'] );

This allows you to get back into object context by calling a specific method on a specific object, as seen in PHP. However, I suppose you could just use the JavaScript bind() function to achieve the same effect.

The event names are not case sensitive, and the prefix "on" is optional. For example, the values "onLoad", "onload" and "load" all mean the same thing.

Your custom function will be passed at least one argument -- a reference to the clipboard client object. However, certain events pass additional arguments, which are described in each section below. The following subsections describe all the available events you can hook.

onLoad

The onLoad event is fired when the Flash movie completes loading and is ready for action. Please note that you don't need to listen for this event to set options -- those are automatically passed to the movie if you call them before it loads. Example use:

	clip.addEventListener( 'onLoad', my_load_handler );
	
	function my_load_handler( client ) {
		alert( "movie has loaded" );
	}