Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 618 lines (416 sloc) 33.329 kb
647dba9 @JamesMGreene Adding dependency badges via DavidDM
JamesMGreene authored
1 ### WARNING
2 **This `master` branch contains the `v2.x` codebase for ZeroClipboard! For the `v1.x` codebase, see the [`1.x-master`](https://github.com/zeroclipboard/zeroclipboard/tree/1.x-master) branch instead.**
73c3e78 @JamesMGreene Added warning to 'instructions.md' about master being v2.x
JamesMGreene authored
3
4
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
5 # Overview
6
1e8c343 @JamesMGreene Updated docs, including explicit security limitations
JamesMGreene authored
7 The ZeroClipboard library provides an easy way to copy text to the clipboard using an invisible [Adobe Flash](http://en.wikipedia.org/wiki/Adobe_Flash) movie and a [JavaScript](http://en.wikipedia.org/wiki/JavaScript) interface. The "Zero" signifies that the library is invisible and the user interface is left entirely up to you.
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
8
1e8c343 @JamesMGreene Updated docs, including explicit security limitations
JamesMGreene authored
9 This is achieved by automatically floating the invisible movie on top of a [DOM](http://en.wikipedia.org/wiki/Document_Object_Model) element of your choice. Standard mouse events are even propagated out to your DOM element, so you can still have rollover and mousedown effects.
10
11
12 ## Limitations
13
6efa213 @JamesMGreene Added notes about CDN and `file://` protocol usage
JamesMGreene authored
14 ### User Interaction Required
15
16 Due to browser and Flash security restrictions, this clipboard injection can _**ONLY**_ occur when
17 the user clicks on the invisible Flash movie. A simulated `click` event from JavaScript will not
18 suffice as this would enable [clipboard poisoning](http://www.computerworld.com/s/article/9117268/Adobe_patches_Flash_clickjacking_and_clipboard_poisoning_bugs).
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
19
75bf289 @JamesMGreene Updates to documentation
JamesMGreene authored
20 ### Synchronicity Required During `copy`
21
22 If a handler of `copy` event intends to modify the pending data for clipboard
23 injection, it _MUST_ operate synchronously in order to maintain the temporarily elevated
24 permissions granted by the user's `click` event. The most common "gotcha" for this restriction is
25 if someone wants to make an asynchronous XMLHttpRequest in response to the `copy` event to get the
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
26 data to inject — this will not work. You must make it a _synchronous_ XMLHttpRequest instead,
27 or do the work in advance before the `copy` event is fired.
28
29 ### Browser-Specific Limitations
30
31 See [Support](#support) and [Browser-Specific Known Issues](#browser-specific-known-issues) below.
75bf289 @JamesMGreene Updates to documentation
JamesMGreene authored
32
33 ### OS-Specific Limitations
34
35 See [OS Considerations](#os-considerations) below.
36
f026369 @JamesMGreene Docs: Updates, including links to new 'starter snippets' on various p…
JamesMGreene authored
37 ### Sandboxing Limitations
38
39 See [`sandbox`ed `iframe` Limitations](#sandboxed-iframe-limitations) below.
40
a9c0509 @JamesMGreene Docs: Added in-depth explanation of `file://` protocol issues and wor…
JamesMGreene authored
41 ### Protocol Limitations
42
43 See [Cross-Protocol Limitations](#cross-protocol-limitations) and [`file://` Protocol Limitations](#file-protocol-limitations) below.
44
45
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
46
f705364 @JamesMGreene Clarified the transient nature of `clip.setText`
JamesMGreene authored
47 ## Installation
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
48
6f5e315 @JamesMGreene Docs: Added lots of version badges
JamesMGreene authored
49 ### [NPM](https://www.npmjs.org/) [![NPM version](https://badge.fury.io/js/zeroclipboard.png)](https://www.npmjs.org/package/zeroclipboard)
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
50
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
51 ```shell
bd049c7 @jonrohan Rewriting the docs and adding some method parody.
jonrohan authored
52 npm install zeroclipboard
53 ```
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
54
6f5e315 @JamesMGreene Docs: Added lots of version badges
JamesMGreene authored
55 ### [Bower](http://bower.io/) [![Bower version](https://badge.fury.io/bo/zeroclipboard.png)](http://bower.io/search/?q=zeroclipboard)
f705364 @JamesMGreene Clarified the transient nature of `clip.setText`
JamesMGreene authored
56
57 ```shell
58 bower install zeroclipboard
59 ```
60
6f5e315 @JamesMGreene Docs: Added lots of version badges
JamesMGreene authored
61 ### [SPM](http://spmjs.io/) [![SPM version](http://spmjs.io/badge/zeroclipboard)](http://spmjs.io/package/zeroclipboard)
4a5d63f @JamesMGreene Adding docs on the alternate installation methods
JamesMGreene authored
62
63 ```shell
64 spm install zeroclipboard
65 ```
66
fcdf868 @JamesMGreene Support: Add official support for ComponentJS
JamesMGreene authored
67 ### [Component](https://github.com/componentjs/component) [![Component version](https://badge.fury.io/gh/zeroclipboard%2Fzeroclipboard.png)](http://component.github.io/?q=zeroclipboard)
68
69 ```shell
70 component install zeroclipboard/zeroclipboard
71 ```
72
6f5e315 @JamesMGreene Docs: Added lots of version badges
JamesMGreene authored
73 ### [PHP Composer](https://getcomposer.org/) [![PHP version](https://badge.fury.io/ph/zeroclipboard%2Fzeroclipboard.svg)](https://packagist.org/packages/zeroclipboard/zeroclipboard)
4a5d63f @JamesMGreene Adding docs on the alternate installation methods
JamesMGreene authored
74
75 For any PHP Composer users, ZeroClipboard is also [available on Packagist](https://packagist.org/packages/zeroclipboard/zeroclipboard).
76
77 ### [Ruby Gem](https://rubygems.org/)
78
79 For any Rails users, the [`zeroclipboard-rails` Ruby Gem](https://rubygems.org/gems/zeroclipboard-rails) is available to automatically add ZeroClipboard into your Rails asset pipeline.
80
f705364 @JamesMGreene Clarified the transient nature of `clip.setText`
JamesMGreene authored
81
6efa213 @JamesMGreene Added notes about CDN and `file://` protocol usage
JamesMGreene authored
82 ## CDN Availability
83
84 If you'd like to use ZeroClipboard hosted via a CDN (content delivery network), you can try:
85
86 - **cdnjs**: http://cdnjs.com/libraries/zeroclipboard
87 - **jsDelivr**: http://www.jsdelivr.com/#!zeroclipboard
88
89
f705364 @JamesMGreene Clarified the transient nature of `clip.setText`
JamesMGreene authored
90 ## Setup
91
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
92 To use the library, simply include the following JavaScript file in your page:
93
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
94 ```html
bd049c7 @jonrohan Rewriting the docs and adding some method parody.
jonrohan authored
95 <script type="text/javascript" src="ZeroClipboard.js"></script>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
96 ```
97
6efa213 @JamesMGreene Added notes about CDN and `file://` protocol usage
JamesMGreene authored
98 You also need to have the "`ZeroClipboard.swf`" file available to the browser. If this file is
99 located in the same directory as your web page, then it will work out of the box. However, if the
100 SWF file is hosted elsewhere, you need to set the URL like this (place this code _after_ the script
101 tag):
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
102
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
103 ```js
6efa213 @JamesMGreene Added notes about CDN and `file://` protocol usage
JamesMGreene authored
104 ZeroClipboard.config( { swfPath: "http://YOURSERVER/path/ZeroClipboard.swf" } );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
105 ```
106
48767f6 @JamesMGreene Docs: Corrected some misinformation about SourceMaps
JamesMGreene authored
107 ### Using the Minified Library
108 If you intend to use the minified version of ZeroClipboard, you will likely also want to do one of the following two things:
90a8b03 @JamesMGreene Docs: Identified the SourceMap file by name
JamesMGreene authored
109 1. Include the SourceMap file ("ZeroClipboard.min.map") in the same hosted directory in order to be able to debug as unminified JavaScript in your browser dev tools.
48767f6 @JamesMGreene Docs: Corrected some misinformation about SourceMaps
JamesMGreene authored
110 2. Open the "ZeroClipboard.min.js" file and remove the last line. It is a comment that begins with `//# sourceMappingURL=`. Removing this line will prevent the browsers' dev tools from requesting the file.
111
112 #### SourceMap Error Messages
113 The SourceMap is not _required_ for normal operation and typically will not be requested by the browser unless the dev tools are open. If you _**do NOT**_ include the SourceMap in your hosted directory [or remove the `sourceMappingURL` comment], then you may see a variety of confusing warnings in your dev tools' JavaScript console:
c11ba11 @robotdan Doc updates for using minified and sourcemap
robotdan authored
114
48767f6 @JamesMGreene Docs: Corrected some misinformation about SourceMaps
JamesMGreene authored
115 ##### Safari
116 ```
ec4e981 @robotdan Add additional details on the use of the source map when using the mi…
robotdan authored
117 [Error] Failed to load resource: the server responded with a status of 404 (Not Found) (ZeroClipboard.min.map, line 0)
118 ```
c11ba11 @robotdan Doc updates for using minified and sourcemap
robotdan authored
119
48767f6 @JamesMGreene Docs: Corrected some misinformation about SourceMaps
JamesMGreene authored
120 ##### Firefox
121 ```
ec4e981 @robotdan Add additional details on the use of the source map when using the mi…
robotdan authored
122 http://YOURSERVER/path/ZeroClipboard.min.js is being assigned a //# sourceMappingURL, but already has one
123 ```
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
124
48767f6 @JamesMGreene Docs: Corrected some misinformation about SourceMaps
JamesMGreene authored
125 ##### Chrome
126 You may not see any error message in Chrome's console. However, you will likely see 404 responses in the Network tab, e.g.
127 ```
128 ZeroClipboard.min.map 404 (Not Found)
129 ```
130
131 ##### IE
132 You will likely see an error message in the Debugger tab.
133
c11ba11 @robotdan Doc updates for using minified and sourcemap
robotdan authored
134
bd049c7 @jonrohan Rewriting the docs and adding some method parody.
jonrohan authored
135 ## Clients
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
136
6efa213 @JamesMGreene Added notes about CDN and `file://` protocol usage
JamesMGreene authored
137 Now you are ready to create one or more _clients_. A client is a single instance of the clipboard
138 library on the page, linked to one or more DOM elements. Here is how to create a client instance:
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
139
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
140 ```js
b2ecc11 @JamesMGreene Removed client singleton pattern.
JamesMGreene authored
141 var client = new ZeroClipboard();
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
142 ```
143
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
144 You can also include an element or array of elements in the new client. _\*\*This example uses jQuery to find "copy buttons"._
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
145
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
146 ```js
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
147 var client = new ZeroClipboard($(".copy-button"));
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
148 ```
149
150
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
151 ## API
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
152
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
153 For the full API documentation, see [api/ZeroClipboard.md](api/ZeroClipboard.md). The full set of
154 [Configuration Options](api/ZeroClipboard.md#configuration-options) are also documented there.
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
155
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
156 For developers who want to wrap ZeroClipboard into a 3rd party plugin
8f02e2e @JamesMGreene Updated path to 'jquery.zeroclipboard'
JamesMGreene authored
157 (e.g. [jquery.zeroclipboard](https://github.com/zeroclipboard/jquery.zeroclipboard)),
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
158 see the [api/ZeroClipboard.Core.md](api/ZeroClipboard.Core.md) documentation instead.
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
159
160
bd049c7 @jonrohan Rewriting the docs and adding some method parody.
jonrohan authored
161 ### Text To Copy
162
f705364 @JamesMGreene Clarified the transient nature of `clip.setText`
JamesMGreene authored
163 Setting the clipboard text can be done in 4 ways:
164
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
165 1. Add a `copy` event handler in which you call `event.clipboardData.setData` to set the appropriate data. This event is triggered every time ZeroClipboard tries to inject into the clipboard. Example:
f705364 @JamesMGreene Clarified the transient nature of `clip.setText`
JamesMGreene authored
166
167 ```js
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
168 client.on( "copy", function (event) {
169 var clipboard = event.clipboardData;
170 clipboard.setData( "text/plain", "Copy me!" );
171 clipboard.setData( "text/html", "<b>Copy me!</b>" );
172 clipboard.setData( "application/rtf", "{\\rtf1\\ansi\n{\\b Copy me!}}" );
f705364 @JamesMGreene Clarified the transient nature of `clip.setText`
JamesMGreene authored
173 });
174 ```
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
175
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
176 2. Set the "text/plain" [and _usually_ "text/html"] clipboard segments via `data-clipboard-target` attribute on the button. ZeroClipboard will look for the target element via ID and try to get the HTML value via `.value`, `.outerHTML`, or `.innerHTML`, and the text value via `.value`, `.textContent`, or `.innerText`. If the HTML and text values for the targeted element match, the value will only be placed into the "text/plain" segment of the clipboard (i.e. the "text/html" segment will cleared).
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
177
c389319 @jonrohan Updating the docs for the datarequested method
jonrohan authored
178 ```html
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
179 <button id="my-button_text" data-clipboard-target="clipboard_text">Copy to Clipboard</button>
180 <button id="my-button_textarea" data-clipboard-target="clipboard_textarea">Copy to Clipboard</button>
181 <button id="my-button_pre" data-clipboard-target="clipboard_pre">Copy to Clipboard</button>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
182
c389319 @jonrohan Updating the docs for the datarequested method
jonrohan authored
183 <input type="text" id="clipboard_text" value="Clipboard Text"/>
184 <textarea id="clipboard_textarea">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
185 tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
186 quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
187 consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
188 cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
189 proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</textarea>
190 <pre id="clipboard_pre">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
191 tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
192 quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
193 consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
194 cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
195 proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</pre>
196 ```
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
197
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
198 3. Set the "text/plain" clipboard segment via `data-clipboard-text` attribute on the button. Doing this will let ZeroClipboard take care of the rest.
c389319 @jonrohan Updating the docs for the datarequested method
jonrohan authored
199
200 ```html
201 <button id="my-button" data-clipboard-text="Copy me!">Copy to Clipboard</button>
202 ```
203
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
204 4. Set the data via the `ZeroClipboard.setData` (any segment) method. You can call this function at any time: when the page first loads, or later like in a `copy` event handler. Example:
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
205
206 ```js
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
207 ZeroClipboard.setData( "text/plain", "Copy me!" );
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
208 ```
209
210 The important caveat of using `ZeroClipboard.setData` is that the data it sets is **transient** and _will only be used for a single copy operation_. As such, we do not particularly
211 recommend using `ZeroClipboard.setData` (and friends) other than inside of a `copy` event handler; however, the API will not prevent you from using it in other ways.
212
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
213 5. Set the data via the `client.setText` ("text/plain" segment), `client.setHtml` ("text/html" segment), `client.setRichText` ("application/rtf" segment), or `client.setData` (any segment) methods. You can call this function at any time: when the page first loads, or later like in a `copy` event handler. Example:
c389319 @jonrohan Updating the docs for the datarequested method
jonrohan authored
214
215 ```js
b2ecc11 @JamesMGreene Removed client singleton pattern.
JamesMGreene authored
216 client.setText( "Copy me!" );
c389319 @jonrohan Updating the docs for the datarequested method
jonrohan authored
217 ```
01c2a48 @jonrohan default cacheBust to true for only IE
jonrohan authored
218
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
219 The important caveat of using `client.setData` (and friends) is that the data it sets is **transient** and _will only be used for a single copy operation_. As such, we do not particularly
220 recommend using `client.setData` (and friends) other than inside of a `copy` event handler; however, the API will not prevent you from using it in other ways.
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
221
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
222
8159d5a @JamesMGreene Deprecated '[un]glue', replaced with '[un]clip'.
JamesMGreene authored
223 ### Clipping
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
224
8159d5a @JamesMGreene Deprecated '[un]glue', replaced with '[un]clip'.
JamesMGreene authored
225 Clipping refers to the process of "linking" the Flash movie to a DOM element on the page. Since the Flash movie is completely transparent, the user sees nothing out of the ordinary.
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
226
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
227 The Flash movie receives the click event and copies the text to the clipboard. Also, mouse actions like hovering and `mousedown` generate events that you can capture (see [_Event Handlers_](#event-handlers) below).
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
228
8159d5a @JamesMGreene Deprecated '[un]glue', replaced with '[un]clip'.
JamesMGreene authored
229 To clip elements, you must pass an element, or array of elements to the `clip` function.
e8f487a @jonrohan updating instructions for new query format
jonrohan authored
230
8159d5a @JamesMGreene Deprecated '[un]glue', replaced with '[un]clip'.
JamesMGreene authored
231 Here is how to clip your client library instance to a DOM element:
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
232
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
233 ```js
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
234 client.clip( document.getElementById("d_clip_button") );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
235 ```
236
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
237 You can pass in a reference to the actual DOM element object itself or an array of DOM objects. 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.
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
238
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
239
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
240 ### Example Implementation
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
241
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
242 ```html
12a6d72 @jonrohan Updating instructions docs. fixes #58
jonrohan authored
243 <button id="my-button" data-clipboard-text="Copy me!" title="Click to copy to clipboard.">Copy to Clipboard</button>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
244 ```
245
246 And the code:
247
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
248 ```js
b2ecc11 @JamesMGreene Removed client singleton pattern.
JamesMGreene authored
249 var client = new ZeroClipboard( $("button#my-button") );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
250 ```
251
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
252
bd049c7 @jonrohan Rewriting the docs and adding some method parody.
jonrohan authored
253 ## CSS Effects
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
254
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
255 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), so long as the `bubbleEvents` configuration property remains set to `true`.
256
257 In addition to this, ZeroClipboard can also manage CSS classes on the clipped elements that mimic the CSS pseudo-classes ":hover" and ":active" on your DOM element. This essentially allows your elements to behave normally, even though the floating Flash movie is the first object receiving all the mouse events during the event bubbling phase. These "pseudo-pseudo-class" names are configurable via the `hoverClass` and `activeClass` configuration properties.
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
258
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
259 Example CSS, targeting a DOM element with a class of "clip_button":
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
260
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
261 ```css
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
262 .clip_button {
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
263 width: 150px;
264 text-align: center;
265 border: 1px solid black;
266 background-color: #ccc;
267 margin: 10px;
268 padding: 10px;
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
269 }
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
270 .clip_button.zeroclipboard-is-hover { background-color: #eee; }
271 .clip_button.zeroclipboard-is-active { background-color: #aaa; }
3ba628c @jrolfs Added documentation for 'off'
jrolfs authored
272 ```
273
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
274
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
275 ## Examples
276
277 The following are complete, working examples of using the clipboard client library in HTML pages.
278
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
279
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
280 ### Minimal Example
281
282 Here is a quick example using as few calls as possible:
283
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
284 ```html
5bca19b @JamesMGreene Event callback model mimics DOM Event API model.
JamesMGreene authored
285 <html>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
286 <body>
bd575f0 @JamesMGreene Added API documentation.
JamesMGreene authored
287 <div id="d_clip_button" class="clip_button" data-clipboard-text="Copy Me!" title="Click to copy." style="border:1px solid black; padding:20px;">Copy To Clipboard</div>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
288
bd049c7 @jonrohan Rewriting the docs and adding some method parody.
jonrohan authored
289 <script type="text/javascript" src="ZeroClipboard.js"></script>
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
290 <script type="text/javascript">
b2ecc11 @JamesMGreene Removed client singleton pattern.
JamesMGreene authored
291 var client = new ZeroClipboard( document.getElementById('d_clip_button') );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
292 </script>
293 </body>
5bca19b @JamesMGreene Event callback model mimics DOM Event API model.
JamesMGreene authored
294 </html>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
295 ```
296
297 When clicked, the text "Copy me!" will be copied to the clipboard.
298
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
299
286c390 @JamesMGreene Added support for RTF, HTML, and custom data formats
JamesMGreene authored
300 ### A More Complete Example
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
301
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
302 Here is a more complete example which exercises many of the configuration options and event handlers:
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
303
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
304 ```html
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
305 <html>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
306 <head>
307 <style type="text/css">
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
308 .clip_button {
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
309 text-align: center;
310 border: 1px solid black;
311 background-color: #ccc;
312 margin: 10px;
313 padding: 10px;
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
314 }
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
315 .clip_button.zeroclipboard-is-hover { background-color: #eee; }
316 .clip_button.zeroclipboard-is-active { background-color: #aaa; }
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
317 </style>
318 </head>
319 <body>
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
320 <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
321 <script type="text/javascript" src="ZeroClipboard.js"></script>
322
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
323 <div class="clip_button">Copy To Clipboard</div>
324 <div class="clip_button">Copy This Too!</div>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
325
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
326 <script type="text/javascript">
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
327 var client = new ZeroClipboard( $('.clip_button') );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
328
5bca19b @JamesMGreene Event callback model mimics DOM Event API model.
JamesMGreene authored
329 client.on( 'ready', function(event) {
330 // console.log( 'movie is loaded' );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
331
5bca19b @JamesMGreene Event callback model mimics DOM Event API model.
JamesMGreene authored
332 client.on( 'copy', function(event) {
333 event.clipboardData.setData('text/plain', event.target.innerHTML);
b2ecc11 @JamesMGreene Removed client singleton pattern.
JamesMGreene authored
334 } );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
335
5bca19b @JamesMGreene Event callback model mimics DOM Event API model.
JamesMGreene authored
336 client.on( 'aftercopy', function(event) {
337 console.log('Copied text to clipboard: ' + event.data['text/plain']);
b2ecc11 @JamesMGreene Removed client singleton pattern.
JamesMGreene authored
338 } );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
339 } );
340
5bca19b @JamesMGreene Event callback model mimics DOM Event API model.
JamesMGreene authored
341 client.on( 'error', function(event) {
342 // console.log( 'ZeroClipboard error of type "' + event.name + '": ' + event.message );
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
343 ZeroClipboard.destroy();
344 } );
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
345 </script>
346 </body>
dece0f4 @JamesMGreene Added better example for gluing multiple elements.
JamesMGreene authored
347 </html>
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
348 ```
349
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
350
f026369 @JamesMGreene Docs: Updates, including links to new 'starter snippets' on various p…
JamesMGreene authored
351 ### "Starter Snippets" for Playground Sites
352
353 - JSFiddle
354 - View: http://fiddle.jshell.net/JamesMGreene/k9psq1da/show/
355 - Edit: http://jsfiddle.net/JamesMGreene/k9psq1da/
356 - CodePen
357 - View: http://s.codepen.io/boomerang/b82185b7ceb35fc9b3829895d38348a31420091710997/index.html
358 - Edit: http://codepen.io/JamesMGreene/pen/zxorvW
359 - JSBin
360 - View: http://jsbin.com/lozuda/
361 - Edit: http://jsbin.com/lozuda/edit?html,js,css
362
363
fa62705 @nason Allow ZeroClipboard DOM attributes to be more configurable.
nason authored
364 ## Namespacing ZeroClipboard
365
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
366 ZeroClipboard creates DOM elements with pre-configured attributes, e.g. a `div` element with an ID of `"global-zeroclipboard-html-bridge"` to encapsulate the Flash object.
fa62705 @nason Allow ZeroClipboard DOM attributes to be more configurable.
nason authored
367
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
368 If you have a need to change the default values, they can be configured by passing in values for `containerId`, `containerClass`, and/or `swfObjectId` using the `ZeroClipboard.config` method. Configuration of these values is completely optional. These values cannot be reconfigured while the ZeroClipboard SWF is actively embedded, and so are completely ignored during that time.
fa62705 @nason Allow ZeroClipboard DOM attributes to be more configurable.
nason authored
369
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
370 Values for `containerId` and `swfObjectId` are validated against the [HTML4 spec for `ID` and `Name` tokens][valid_ids].
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
371
fa62705 @nason Allow ZeroClipboard DOM attributes to be more configurable.
nason authored
372
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
373 ## AMD
374
245b4c5 @JamesMGreene Updated docs and builds for v1.2.0-beta.2
JamesMGreene authored
375 If using [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD) with a library such as [RequireJS](http://requirejs.org/), etc., you shouldn't need to do any special configuration for ZeroClipboard to work correctly as an AMD module.
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
376
377
e7917aa @JamesMGreene Removing the middle man for AMD/CommonJS loaders
JamesMGreene authored
378 ## CommonJS
379
380 If using [CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1) with a library such as [Browserify](http://browserify.org/), [Webmake](https://github.com/medikoo/modules-webmake), etc., you shouldn't need to do any special configuration for ZeroClipboard to work correctly as an CommonJS module.
ea5f231 @JamesMGreene Completing AMD support. Fixes #98. Fixes #99. Fixes #101. Closes #111.
JamesMGreene authored
381
dc50dda @JamesMGreene Docs: Updated documentation, mostly with regard to security.
JamesMGreene authored
382
b31ede5 @JamesMGreene Added documentation for Bootstrap Modal issue.
JamesMGreene authored
383 ## Known Conflicts With Other Libraries
384
8159d5a @JamesMGreene Deprecated '[un]glue', replaced with '[un]clip'.
JamesMGreene authored
385 ### [IE freezes when clicking a ZeroClipboard clipped element within a Bootstrap Modal](https://github.com/zeroclipboard/zeroclipboard/issues/159).
b31ede5 @JamesMGreene Added documentation for Bootstrap Modal issue.
JamesMGreene authored
386 - **Cause:** Bootstrap's Modal has an `enforceFocus` function that tries to keep the focus on the modal.
feb6e86 @JamesMGreene Added documentation for jQuery UI Modal issue.
JamesMGreene authored
387 However, since the ZeroClipboard container is an immediate child of the `body`, this enforcement conflicts. Note that
388 this workaround actually _overrides_ a core Bootstrap Modal function, and as such must be kept in sync as this function
389 changes in future versions of Bootstrap.
b31ede5 @JamesMGreene Added documentation for Bootstrap Modal issue.
JamesMGreene authored
390 - **Workaround:** _Targeted against [Bootstrap v3.x](https://github.com/twbs/bootstrap/blob/96a9e1bae06cb21f8cf72ec528b8e31b6ab27272/js/modal.js#L115-123)._
391
57e8434 @JamesMGreene Docs: Added a simpler workaround for Bootstrap modals
JamesMGreene authored
392 #### Workaround A
393
394 ```js
395 if (/MSIE|Trident/.test(window.navigator.userAgent)) {
396 (function($) {
397 var zcContainerId = ZeroClipboard.config('containerId');
398 $('#' + zcContainerId).on('focusin', false);
399 })(window.jQuery);
400 }
401 ```
402
403 #### Workaround B
404
b31ede5 @JamesMGreene Added documentation for Bootstrap Modal issue.
JamesMGreene authored
405 ```js
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
406 if (/MSIE|Trident/.test(window.navigator.userAgent)) {
407 (function($) {
505fdf2 @JamesMGreene Docs: Fixed a critical typo in the workarounds for modals
JamesMGreene authored
408 var zcClass = '.' + ZeroClipboard.config('containerClass');
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
409 var proto = $.fn.modal.Constructor.prototype;
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
410 proto.enforceFocus = function() {
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
411 $(document)
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
412 .off('focusin.bs.modal') /* Guard against infinite focus loop */
413 .on('focusin.bs.modal', $.proxy(function(e) {
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
414 if (this.$element[0] !== e.target &&
415 !this.$element.has(e.target).length &&
416 /* Adding this final condition check is the only real change */
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
417 !$(e.target).closest(zcClass).length
418 ) {
419 this.$element.focus();
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
420 }
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
421 }, this));
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
422 };
423 })(window.jQuery);
424 }
b31ede5 @JamesMGreene Added documentation for Bootstrap Modal issue.
JamesMGreene authored
425 ```
426
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
427
8159d5a @JamesMGreene Deprecated '[un]glue', replaced with '[un]clip'.
JamesMGreene authored
428 ### [IE freezes when clicking a ZeroClipboard clipped element within a jQuery UI [Modal] Dialog](https://github.com/zeroclipboard/zeroclipboard/issues/159).
feb6e86 @JamesMGreene Added documentation for jQuery UI Modal issue.
JamesMGreene authored
429 - **Cause:** jQuery UI's Dialog (with `{ modal: true }` set) has a `_keepFocus` function that tries to keep the focus on the modal.
430 However, since the ZeroClipboard container is an immediate child of the `body`, this enforcement conflicts. Luckily, jQuery UI offers
431 more natural extension points than Bootstrap, so the workaround is smaller and less likely to be broken in future versions.
432 - **Workaround:** _Targeted against [jQuery UI v1.10.x](https://github.com/jquery/jquery-ui/blob/457b275880b63b05b16b7c9ee6c22f29f682ebc8/ui/jquery.ui.dialog.js#L695-703)._
433
434 ```js
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
435 if (/MSIE|Trident/.test(window.navigator.userAgent)) {
436 (function($) {
505fdf2 @JamesMGreene Docs: Fixed a critical typo in the workarounds for modals
JamesMGreene authored
437 var zcClass = '.' + ZeroClipboard.config('containerClass');
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
438 $.widget( 'ui.dialog', $.ui.dialog, {
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
439 _allowInteraction: function( event ) {
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
440 return this._super(event) || $( event.target ).closest( zcClass ).length;
0dcdd0f @JamesMGreene Updated modal hacks to test for IE userAgent first
JamesMGreene authored
441 }
442 } );
443 })(window.jQuery);
444 }
feb6e86 @JamesMGreene Added documentation for jQuery UI Modal issue.
JamesMGreene authored
445 ```
446
b31ede5 @JamesMGreene Added documentation for Bootstrap Modal issue.
JamesMGreene authored
447
50c4716 @JamesMGreene Dropping support for IE<9
JamesMGreene authored
448 ## Support
841eaa1 @jonrohan adding instructions from old wiki
jonrohan authored
449
50c4716 @JamesMGreene Dropping support for IE<9
JamesMGreene authored
450 This library is fully compatible with Flash Player 11.0.0 and above, which requires
451 that the clipboard copy operation be initiated by a user click event inside the
452 Flash movie. This is achieved by automatically floating the invisible movie on top
453 of a [DOM](http://en.wikipedia.org/wiki/Document_Object_Model) element of your
454 choice. Standard mouse events are even propagated out to your DOM element, so you
455 can still have rollover and mousedown effects with just a _little_ extra effort.
456
457 ZeroClipboard `v2.x` is expected to work in IE9+ and all of the evergreen browsers.
044d96b @JamesMGreene Docs: Noted that IE7-8 support technically existed through `v2.0.2`
JamesMGreene authored
458 Although support for IE7 & IE8 was officially dropped in `v2.0.0`, it was actually
459 still _technically_ supported through `v2.0.2`.
e7917aa @JamesMGreene Removing the middle man for AMD/CommonJS loaders
JamesMGreene authored
460
25ae6ef @JamesMGreene Fix and deprecate the 'setHandCursor' method.
JamesMGreene authored
461
462
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
463 ## Browser-Specific Known Issues
464
465 ### Opera
466 - [Issue #459](https://github.com/zeroclipboard/zeroclipboard/issues/459)
467 - **Problem:** Both the implicit observation of clipped elements' `cursor` CSS property and the `forceHandCursor: true` [Configuration Option](api/ZeroClipboard.md#configuration-options) cannot be honored in Opera's NPAPI Flash Player plugin.
b45e5e1 @JamesMGreene Docs: Added new info from Opera about future of PPAPI Flash plugin usage
JamesMGreene authored
468 - **Workaround:** End users must install both Opera 24+ **AND** the separate PPAPI Flash Player plugin that is currently only available in [Adobe Flash Player 16 Beta](http://labs.adobe.com/downloads/flashplayer.html) (look for the OS-specific download entitled "Download Flash Player for Opera and Chromium based applications – PPAPI"). Beginning with Opera 27 (currently in the alpha/dev channel cycle), Opera will automatically warn users that only have the NPAPI Flash Player plugin installed and guide them into installing the PPAPI Flash Player plugin from Adobe.
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
469
470
471
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
472 ## OS Considerations
473
474 Because ZeroClipboard will be interacting with your users' system clipboards, there are some special considerations
475 specific to the users' operating systems that you should be aware of. With this information, you can make informed
476 decisions of how _your_ site should handle each of these situations.
477
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
478 ### Windows
479 - If you want to ensure that your Windows users will be able to paste their copied text into Windows
480 Notepad and have it honor line breaks, you'll need to ensure that the text uses the sequence `\r\n`
481 instead of just `\n` for line breaks. If the text to copy is based on user input (e.g. a `textarea`),
482 then you can achieve this transformation by utilizing the `copy` event handler, e.g.
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
483
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
484 ```js
485 client.on('copy', function(event) {
486 var text = document.getElementById('yourTextArea').value;
487 var windowsText = text.replace(/\n/g, '\r\n');
488 event.clipboardData.setData('text/plain', windowsText);
489 });
490 ```
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
491
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
492 ### Linux
493 - The Linux Clipboard system (a.k.a. "Selection Atoms" within the [X Consortium's Standard Inter-Client Communication Conventions Manual](http://www.x.org/docs/ICCCM/icccm.pdf)) is a complex but capable setup. However, for normal end users, it stinks. Flash Player's Clipboard API can either:
494 1. Insert plain text into the "System Clipboard" and have it available everywhere; or
495 2. Insert plain, HTML, and RTF text into the "Desktop Clipboard" but it will only be available in applications whose UI are managed by the Desktop Manager System (e.g. GNOME, etc.). This, for example, means that a user on a typical Linux configuration would not be able to paste something copied with ZeroClipboard into a terminal shell but they may still be able to paste it into OpenOffice, the browser, etc.
75bf289 @JamesMGreene Updates to documentation
JamesMGreene authored
496
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
497 As such, the default behavior for ZeroClipboard while running on Linux is to only inject plain text into the "System Clipboard" to cover the most bases. If you want to ignore that caution and use the "Desktop Clipboard" anyway, just set the `forceEnhancedClipboard` [configuration option](api/ZeroClipboard.md#configuration-options) to `true`, i.e.:
75bf289 @JamesMGreene Updates to documentation
JamesMGreene authored
498
499 ```js
500 ZeroClipboard.config({
501 forceEnhancedClipboard: true
502 });
503 ```
504
fb364b3 @JamesMGreene Docs: Added 'Browser-Specific Known Issues' section
JamesMGreene authored
505 Also, a final related behavioral caveat: if the pending clipboard data **ONLY** contains data of the
506 format `"text/plain"`, ZeroClipboard will intelligently choose to use the "System Clipboard" regardless
507 of the `forceEnhancedClipboard` configuration property value.
508
6560660 @JamesMGreene Added "OS Considerations" section (e.g. dealing w/ Windows line breaks)
JamesMGreene authored
509
510
f026369 @JamesMGreene Docs: Updates, including links to new 'starter snippets' on various p…
JamesMGreene authored
511 ## Security Limitations
512
513 ### `sandbox`ed `iframe` Limitations
514
515 The `sandbox` attribute of the `iframe` element (new in HTML5, supported in IE10+ and all other evergreen browsers) provides web developers with a way tighten the restrictions on framed content beyond what Content Security Policy (CSP) provides for un`sandbox`ed cross-origin `iframe`s. With the `sandbox` attribute, you can instruct the browser to load a specific frame's content in a low-privilege environment, starting with the least privilege possible and then whitelisting the necessary subset of capabilities.
516
517 It is also very important to note, however, that the `sandbox` attribute takes away some privileges from the framed content that **CANNOT** be whitelisted "back in". For example, any framed page running in a sandbox absolutely _cannot_ run native plugins (e.g. Flash, Silverlight, Java, etc.). This decision was made because native plugins run unmanaged code that the browser cannot offer any further security verifications on, and are frequently sourced from third parties.
518
519 As such, ZeroClipboard is completely unusable inside of a `sandbox`ed `iframe`. Best efforts have been taken to detect sandboxing and notify consumers via an `error` event (`error[name = "flash-sandboxed"]`) but, unfortunately, not all configurations of sandboxing can be reliably detected from within the framed content.
520
521 This sandboxing is also why ZeroClipboard cannot be used as normal on many online code playground sites like JSFiddle, CodePen, etc. However, we have put together a few ["starter snippets" for such sites](#starter-snippets-for-playground-sites) to get you up and running quickly.
522
523 For a deeper analysis and a few _"naughty"_ workarounds (which only work in limited situations), check
524 out the [sandblaster.js (JamesMGreene/sandblaster)](https://github.com/JamesMGreene/sandblaster) project.
525
526 #### See Also
527
528 - [HTML5 Rocks :metal: article on `sandbox`ed `iframe`s](http://www.html5rocks.com/en/tutorials/security/sandboxed-iframes/)
529 - [HTML spec: `iframe` `sandbox` attribute](https://html.spec.whatwg.org/multipage/embedded-content.html#attr-iframe-sandbox)
530 - [HTML spec: Browser sandboxing](http://www.w3.org/TR/html/browsers.html#sandboxing)
531 - [HTML5 Rocks :metal: article on Content Security Policy (CSP)](http://www.html5rocks.com/en/tutorials/security/content-security-policy/)
532
a9c0509 @JamesMGreene Docs: Added in-depth explanation of `file://` protocol issues and wor…
JamesMGreene authored
533
534 ### Cross-Protocol Limitations
535
536 ZeroClipboard was intentionally configured to _not_ allow the SWF to be served from a secure domain (HTTPS) but scripted by an insecure domain (HTTP).
537
538 If you find yourself in this situation (as in [Issue #170](https://github.com/zeroclipboard/zeroclipboard/issues/170)), please consider the following options:
539 1. Serve the SWF over HTTP instead of HTTPS. If the page's protocol can vary (e.g. authorized/unauthorized, staging/production, etc.), you should include add the SWF with a relative protocol (`//s3.amazonaws.com/blah/ZeroClipboard.swf`) instead of an absolute protocol (`https://s3.amazonaws.com/blah/ZeroClipboard.swf`).
540 2. Serve the page over HTTPS instead of HTTP. If the page's protocol can vary, see the note on the previous option (1).
541 3. Fork ZeroClipboard and update "src/flash/ZeroClipboard.as" to call the [`allowInsecureDomain`](http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/system/Security.html#allowInsecureDomain\(\)) method as needed, then recompile the SWF with your custom changes.
542
543
544 ### `file://` Protocol Limitations
545
546 If you want to either use ZeroClipboard on a page hosted via the `file://` protocol or serve ZeroClipboard's assets via the `file://` protocol, you are almost guaranteed to run into some roadblocks due to Flash Player security restrictions. Whether you will be able to work around these roadblocks depends heavily on the specifics of the browser and Flash Player plugin being used.
547
548 The various potential and/or partial workarounds are detailed below. We recommend trying them in the
549 order they are listed, with the exception of any that are not applicable to your browser/Flash setup.
550
551 #### Stop Hosting It Over The `file://` Protocol
552
553 Do you really need to be hosting this via the `file://` protocol? If not, please don't: it may turn into a neverending (or outright _losing_) security configuration battle for you.
554
555 We recommend that you instead just get a simple HTTP server installed and use it. Many HTTP server applications exist today that don't even require configuration or proper "installation", they are just executable files that can dynamically host the current working directory (or accept command line configuration options). Simple, easy, done.
556
557 But, if you really do _need_ to be hosting this via the `file://` protocol, please read on... and we wish you much-needed luck.
558
559
560 #### Tell ZeroClipboard To Trust Anyone & Everyone
561
562 Rarely, for some browser/Flash setups, you can bypass this security restriction as easily as specifically
563 configuring ZeroClipboard to trust ALL domains for SWF interaction via a wildcard. This
564 configuration must be set _before_ creating ZeroClipboard client instances as a typical consumer,
565 or before calling `ZeroClipboard.create()` in a 3rd party wrapper:
566
567 ```js
568 ZeroClipboard.config({ trustedDomains: ["*"] });
569 ```
570
571 This wildcard configuration should _**NOT**_ be used in environments hosted over HTTP/HTTPS.
572
573
574 #### Tell Flash Player Local Settings Manager To Trust Your SWF URL
575
576 If you are using any browser with the traditional NPAPI Flash Player plugin enabled **AND** _preferred_
577 (i.e. PPAPI Flash Player plugins are not supported, are not installed, or are disabled for the browser
578 instance in question) or using the PPAPI Flash Player plugin `v16.0.0` (or higher), you can edit your
579 system-level Flash Player security settings to whitelist your SWF URL using the [Flash Player
580 Local Settings Manager](http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager.html):
581 1. Open the Flash Player Local Settings Manager via your system's [OS-specific access procedure](http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager.html#124401).
582 2. Go to the ["Advanced" tab](http://help.adobe.com/en_US/FlashPlayer/LSM/WS6aa5ec234ff3f285139dc56112e3786b68c-7ff0.html).
583 3. Locate the ["Developer Tools" subsection](http://help.adobe.com/en_US/FlashPlayer/LSM/WS6aa5ec234ff3f285139dc56112e3786b68c-7ff0.html#WS6aa5ec234ff3f285139dc56112e3786b68c-7feb) (may require you to scroll down).
584 4. Click the ["Trusted Location Settings..." button](http://help.adobe.com/en_US/FlashPlayer/LSM/WS6aa5ec234ff3f285139dc56112e3786b68c-7ff0.html#WS6aa5ec234ff3f285139dc56112e3786b68c-7fea).
585 5. Click "Add location" (may be represented as a `+` button).
586 6. Add the absolute path of your local "ZeroClipboard.swf" file to the trusted files whitelist.
587
588 This should work for all NPAPI Flash Player plugins. However, this _may_ **not** work for all PPAPI Flash Player plugins.
589
590
591 #### Tell Flash Player Online Settings Manager To Trust Your SWF URL
592
593 If you are using any browser with the traditional NPAPI Flash Player plugin enabled **AND** _preferred_
594 (i.e. PPAPI Flash Player plugins are not supported, are not installed, or are disabled for the browser
595 instance in question), you can edit your device-level NPAPI Flash Player security settings to whitelist
596 your SWF URL using the [Flash Player Online Settings Manager](http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html):
597 1. Using the same browser, go to the [Adobe Flash Player Online Settings Manager page](http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html).
598 2. In the small embedded Flash app (which looks more like a screen capture rather than an interactive UI), click "Add location". This may be inside of an "Edit locations..." dropdown menu.
599 3. Add the absolute path of your local "ZeroClipboard.swf" file to the trusted files whitelist.
600
601 Some versions of Flash also include an "allow all" option in the Global Settings Manager.
602
603 This should work for all NPAPI Flash Player plugins. However, this **WILL NOT** work for _any_ PPAPI Flash Player plugins.
604
605
606 #### Tell PPAPI Flash Player Plugins To Take A Hike
607
608 If you are using a PPAPI Flash Player plugin and all of the aforementioned workarounds **combined** still didn't allow you to bypass this security restriction, you have officially run out of proper workarounds as you have almost certainly run into the [even more restrictive security model in Chromium's "Pepper" (PPAPI) Flash layer](https://code.google.com/p/chromium/issues/detail?id=137734). This elevated security will affect PPAPI Flash Player plugin usage in Chromium, Chrome Canary, Chrome, and possibly all Blink-based versions of Opera.
609
610 At this point, your only remaining option is to disable your PPAPI Flash Player plugin and fallback to an NPAPI Flash Player plugin instead.
611
612 If you are unwilling to disable your PPAPI Flash Player plugin, your goal has now officially been defeated by Flash Player's security restrictions. You should now reconsider our earlier recommendation to [stop hosting it over the `file://` protocol](#stop-hosting-it-over-the-file-protocol)... we _tried_ to warn you!
613
614
615
1f8b8f6 @JamesMGreene Merging PR #413.
JamesMGreene authored
616
68572da @JamesMGreene MouseEvent cleanup... as best as possible.
JamesMGreene authored
617 [valid_ids]: http://www.w3.org/TR/html4/types.html#type-id "HTML4 specification for `ID` and `Name` tokens"
Something went wrong with that request. Please try again.