scratch – Blame information for rev 125

Subversion Repositories:
Rev:
Rev Author Line No. Line
58 office 1 # clipboard.js
2  
3 [![Build Status](http://img.shields.io/travis/zenorocha/clipboard.js/master.svg?style=flat)](https://travis-ci.org/zenorocha/clipboard.js)
4 ![Killing Flash](https://img.shields.io/badge/killing-flash-brightgreen.svg?style=flat)
5  
6 > Modern copy to clipboard. No Flash. Just 3kb gzipped.
7  
8 <a href="https://clipboardjs.com/"><img width="728" src="https://cloud.githubusercontent.com/assets/398893/16165747/a0f6fc46-349a-11e6-8c9b-c5fd58d9099c.png" alt="Demo"></a>
9  
10 ## Why
11  
12 Copying text to the clipboard shouldn't be hard. It shouldn't require dozens of steps to configure or hundreds of KBs to load. But most of all, it shouldn't depend on Flash or any bloated framework.
13  
14 That's why clipboard.js exists.
15  
16 ## Install
17  
18 You can get it on npm.
19  
20 ```
21 npm install clipboard --save
22 ```
23  
125 office 24 Or if you're not into package management, just [download a ZIP](https://github.com/zenorocha/clipboard.js/archive/master.zip) file.
58 office 25  
26 ## Setup
27  
28 First, include the script located on the `dist` folder or load it from [a third-party CDN provider](https://github.com/zenorocha/clipboard.js/wiki/CDN-Providers).
29  
30 ```html
31 <script src="dist/clipboard.min.js"></script>
32 ```
33  
34 Now, you need to instantiate it by [passing a DOM selector](https://github.com/zenorocha/clipboard.js/blob/master/demo/constructor-selector.html#L18), [HTML element](https://github.com/zenorocha/clipboard.js/blob/master/demo/constructor-node.html#L16-L17), or [list of HTML elements](https://github.com/zenorocha/clipboard.js/blob/master/demo/constructor-nodelist.html#L18-L19).
35  
36 ```js
37 new Clipboard('.btn');
38 ```
39  
40 Internally, we need to fetch all elements that matches with your selector and attach event listeners for each one. But guess what? If you have hundreds of matches, this operation can consume a lot of memory.
41  
42 For this reason we use [event delegation](http://stackoverflow.com/questions/1687296/what-is-dom-event-delegation) which replaces multiple event listeners with just a single listener. After all, [#perfmatters](https://twitter.com/hashtag/perfmatters).
43  
44 # Usage
45  
46 We're living a _declarative renaissance_, that's why we decided to take advantage of [HTML5 data attributes](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_data_attributes) for better usability.
47  
48 ### Copy text from another element
49  
50 A pretty common use case is to copy content from another element. You can do that by adding a `data-clipboard-target` attribute in your trigger element.
51  
52 The value you include on this attribute needs to match another's element selector.
53  
54 <a href="https://clipboardjs.com/#example-target"><img width="473" alt="example-2" src="https://cloud.githubusercontent.com/assets/398893/9983467/a4946aaa-5fb1-11e5-9780-f09fcd7ca6c8.png"></a>
55  
56 ```html
57 <!-- Target -->
58 <input id="foo" value="https://github.com/zenorocha/clipboard.js.git">
59  
60 <!-- Trigger -->
61 <button class="btn" data-clipboard-target="#foo">
62 <img src="assets/clippy.svg" alt="Copy to clipboard">
63 </button>
64 ```
65  
66 ### Cut text from another element
67  
68 Additionally, you can define a `data-clipboard-action` attribute to specify if you want to either `copy` or `cut` content.
69  
70 If you omit this attribute, `copy` will be used by default.
71  
72 <a href="https://clipboardjs.com/#example-action"><img width="473" alt="example-3" src="https://cloud.githubusercontent.com/assets/398893/10000358/7df57b9c-6050-11e5-9cd1-fbc51d2fd0a7.png"></a>
73  
74 ```html
75 <!-- Target -->
76 <textarea id="bar">Mussum ipsum cacilds...</textarea>
77  
78 <!-- Trigger -->
79 <button class="btn" data-clipboard-action="cut" data-clipboard-target="#bar">
80 Cut to clipboard
81 </button>
82 ```
83  
84 As you may expect, the `cut` action only works on `<input>` or `<textarea>` elements.
85  
86 ### Copy text from attribute
87  
88 Truth is, you don't even need another element to copy its content from. You can just include a `data-clipboard-text` attribute in your trigger element.
89  
90 <a href="https://clipboardjs.com/#example-text"><img width="147" alt="example-1" src="https://cloud.githubusercontent.com/assets/398893/10000347/6e16cf8c-6050-11e5-9883-1c5681f9ec45.png"></a>
91  
92 ```html
93 <!-- Trigger -->
94 <button class="btn" data-clipboard-text="Just because you can doesn't mean you should — clipboard.js">
95 Copy to clipboard
96 </button>
97 ```
98  
99 ## Events
100  
101 There are cases where you'd like to show some user feedback or capture what has been selected after a copy/cut operation.
102  
103 That's why we fire custom events such as `success` and `error` for you to listen and implement your custom logic.
104  
105 ```js
106 var clipboard = new Clipboard('.btn');
107  
108 clipboard.on('success', function(e) {
109 console.info('Action:', e.action);
110 console.info('Text:', e.text);
111 console.info('Trigger:', e.trigger);
112  
113 e.clearSelection();
114 });
115  
116 clipboard.on('error', function(e) {
117 console.error('Action:', e.action);
118 console.error('Trigger:', e.trigger);
119 });
120 ```
121  
122 For a live demonstration, open this [site](https://clipboardjs.com/) and just your console :)
123  
124 ## Advanced Options
125  
126 If you don't want to modify your HTML, there's a pretty handy imperative API for you to use. All you need to do is declare a function, do your thing, and return a value.
127  
128 For instance, if you want to dynamically set a `target`, you'll need to return a Node.
129  
130 ```js
131 new Clipboard('.btn', {
132 target: function(trigger) {
133 return trigger.nextElementSibling;
134 }
135 });
136 ```
137  
138 If you want to dynamically set a `text`, you'll return a String.
139  
140 ```js
141 new Clipboard('.btn', {
142 text: function(trigger) {
143 return trigger.getAttribute('aria-label');
144 }
145 });
146 ```
147  
125 office 148 For use in Bootstrap Modals or with any other library that changes the focus you'll want to set the focused element as the `container` value.
149  
150 ```js
151 new Clipboard('.btn', {
152 container: document.getElementById('#modal')
153 });
154 ```
155  
58 office 156 Also, if you are working with single page apps, you may want to manage the lifecycle of the DOM more precisely. Here's how you clean up the events and objects that we create.
157  
158 ```js
159 var clipboard = new Clipboard('.btn');
160 clipboard.destroy();
161 ```
162  
163 ## Browser Support
164  
165 This library relies on both [Selection](https://developer.mozilla.org/en-US/docs/Web/API/Selection) and [execCommand](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand) APIs. The first one is [supported by all browsers](http://caniuse.com/#search=selection) while the second one is supported in the following browsers.
166  
167 | <img src="https://clipboardjs.com/assets/images/chrome.png" width="48px" height="48px" alt="Chrome logo"> | <img src="https://clipboardjs.com/assets/images/edge.png" width="48px" height="48px" alt="Edge logo"> | <img src="https://clipboardjs.com/assets/images/firefox.png" width="48px" height="48px" alt="Firefox logo"> | <img src="https://clipboardjs.com/assets/images/ie.png" width="48px" height="48px" alt="Internet Explorer logo"> | <img src="https://clipboardjs.com/assets/images/opera.png" width="48px" height="48px" alt="Opera logo"> | <img src="https://clipboardjs.com/assets/images/safari.png" width="48px" height="48px" alt="Safari logo"> |
168 |:---:|:---:|:---:|:---:|:---:|:---:|
169 | 42+ ✔ | 12+ ✔ | 41+ ✔ | 9+ ✔ | 29+ ✔ | 10+ ✔ |
170  
171 The good news is that clipboard.js gracefully degrades if you need to support older browsers. All you have to do is show a tooltip saying `Copied!` when `success` event is called and `Press Ctrl+C to copy` when `error` event is called because the text is already selected.
172  
173 You can also check if clipboard.js is supported or not by running `Clipboard.isSupported()`, that way you can hide copy/cut buttons from the UI.
174  
125 office 175 ## Bonus
176  
177 A browser extension that adds a "copy to clipboard" button to every code block on *GitHub, MDN, Gist, StackOverflow, StackExchange, npm, and even Medium.*
178  
179 Install for [Chrome](https://chrome.google.com/webstore/detail/codecopy/fkbfebkcoelajmhanocgppanfoojcdmg) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/codecopy/).
180  
58 office 181 ## License
182  
183 [MIT License](http://zenorocha.mit-license.org/) © Zeno Rocha