Tutorial #52
Clipboard API / ZeroClipboard Intermediate   2014-03-28

Introduction

At some point most developers find themselves wanting an easy way to copy text from part of a web page into the user's Clipboard so they can paste it into another application. Of course, users can do this form themselves by select, copy and paste but that is prone to errors if the text is something complex, like a license key, and the user fails to select on the precise boundaries of the text.

The problem with this feature is that a malicious developer might insert text into the clipboard without the user being aware. Unknowingly inserting this into a desktop application would be a potential security risk. As a result, JavaScript and HTML do not provide a way to do this - until now...

The specification for HTML5 includes a Clipboard API which aims to handle security concerns while making it easy to copy text. Unfortunately this is still a draft specification (as of April 2014) and, while the major browsers are working on implementations, this API is not ready for production use at all. As this API matures I will update this tutorial or write a seprarate one.


In the interim we can use a tool called ZeroClipboard which uses JavaScript and a hidden Adobe Flash movie to get around the current limitations of HTML.

Now if this sounds like a bit of a hack, well, it is - but it works... it works really well - and for now it is the best solution

This tutorial shows how to incorporate ZeroClipboard into your pages

Demo 1 screenshot for this tutorial

The trick to ZeroClipboard is the use of an 'invisible' Adobe Flash movie. You include the special ZeroClipboad.swf movie file and the JavaScript library ZeroClipboard.js in your page and write your own calls to the library to tie it all together. You don't need to know anything about the movie file or how all this magic works - it just does...

Because ZeroClipboard uses a Flash movie, your users obviously need to have Adobe Flash installed. This won't be a problem in most cases but you do need to handle the case where it is not present.


Understanding the Code

The demo shows a block of text followed by a 'Copy to Clipboard' button. Clicking the button does what it says and you can paste that into any other application, or into the textarea that is shown below the button.

Note that the text copied retains any line breaks in the original text, so the layout of the pasted text looks different from the HTML version, where line breaks are ignored.

In order to use ZeroClipboard you need to download two files. The easiest way to do this is to download the ZIP file from zeroclipbaod.org (look on the left side of the page - current version is 1.3.5). Unpack this somewhere and look in the top level folder.

You want to copy ZeroClipboard.swf and ZeroClipboard.min.js into your site's directories. You can ignore the rest of the files, unless you are using tools like Grunt and Bower to manage your libraries.

You will see other ways to use the library in the ZeroClipboard documentation, but the one shown here seems to be the easiest.

The HTML code in the demo sets up a block of text that we want to copy in a p tag pair that is given a unique id so we can access it later. The Button is also given a unique id

Within the JavaScript block we first specify the location of the ZeroClipboard.swf movie file. I prefer to keep this in the same directory as the ZeroClipboard.js file. You specify the location with this config call:

ZeroClipboard.config( { moviePath: 'javascripts/ZeroClipboard.swf' } );

Next we create a ZeroClipboard object, passing it the DOM element is the button. Here I am using the jQuery way of doing this.

The library uses its own event handlers and here we bind two top level handlers to the load event (when the page is loaded) and the wrongflash and noflash events which are triggered if Flash is not available in the browser or is an invalid version.

Within the load event handler

we define a datarequested handler which is triggered when the Copy to Clipboard button is clicked. This gets the text from the para with the desired text and passes it to the ZeroClipboard object with setText.

In the demo I copy the text using the text() method, which strips any HTML formatting from the text. If you want to preserve this then use html().

Once triggered, this makes the text available for pasting. But we can add a second event handler if we want to check that copying has been successful. That is what the complete handler does here, which outputs the copied text in the browser console. It is not required.

As you can see, the library is really simple to use. There is magic at work behind the scenes but that really doesn't concern us. There are other configuration options that might be useful - check out the documentation on the github site shown below.

The stable release of ZeroClipboard is version 1.3.5 but a 2.x version can be found on the ZeroClipboard Github site. The authors state that this new version is unstable (as of April 2014) and so the demo here uses v1.3.5


More Information

W3C Clipboard API and events (draft)

ZeroClipboard

ZeroClipboard on Github


Code for this Tutorial


Share this tutorial



Comment on this Tutorial


comments powered by Disqus