scratch – Diff between revs 58 and 125

Subversion Repositories:
Rev:
Only display areas with differences – Ignore whitespace
Rev 58 Rev 125
1 # clipboard.js 1 # clipboard.js
2   2  
3 [![Build Status](http://img.shields.io/travis/zenorocha/clipboard.js/master.svg?style=flat)](https://travis-ci.org/zenorocha/clipboard.js) 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) 4 ![Killing Flash](https://img.shields.io/badge/killing-flash-brightgreen.svg?style=flat)
5   5  
6 > Modern copy to clipboard. No Flash. Just 3kb gzipped. 6 > Modern copy to clipboard. No Flash. Just 3kb gzipped.
7   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> 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   9  
10 ## Why 10 ## Why
11   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. 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   13  
14 That's why clipboard.js exists. 14 That's why clipboard.js exists.
15   15  
16 ## Install 16 ## Install
17   17  
18 You can get it on npm. 18 You can get it on npm.
19   19  
20 ``` 20 ```
21 npm install clipboard --save 21 npm install clipboard --save
22 ``` 22 ```
23   -  
24 Or bower, too. -  
25   -  
26 ``` -  
27 bower install clipboard --save -  
28 ``` -  
29   23  
30 If you're not into package management, just [download a ZIP](https://github.com/zenorocha/clipboard.js/archive/master.zip) file. 24 Or if you're not into package management, just [download a ZIP](https://github.com/zenorocha/clipboard.js/archive/master.zip) file.
31   25  
32 ## Setup 26 ## Setup
33   27  
34 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). 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).
35   29  
36 ```html 30 ```html
37 <script src="dist/clipboard.min.js"></script> 31 <script src="dist/clipboard.min.js"></script>
38 ``` 32 ```
39   33  
40 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). 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).
41   35  
42 ```js 36 ```js
43 new Clipboard('.btn'); 37 new Clipboard('.btn');
44 ``` 38 ```
45   39  
46 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. 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.
47   41  
48 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). 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).
49   43  
50 # Usage 44 # Usage
51   45  
52 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. 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.
53   47  
54 ### Copy text from another element 48 ### Copy text from another element
55   49  
56 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. 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.
57   51  
58 The value you include on this attribute needs to match another's element selector. 52 The value you include on this attribute needs to match another's element selector.
59   53  
60 <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> 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>
61   55  
62 ```html 56 ```html
63 <!-- Target --> 57 <!-- Target -->
64 <input id="foo" value="https://github.com/zenorocha/clipboard.js.git"> 58 <input id="foo" value="https://github.com/zenorocha/clipboard.js.git">
65   59  
66 <!-- Trigger --> 60 <!-- Trigger -->
67 <button class="btn" data-clipboard-target="#foo"> 61 <button class="btn" data-clipboard-target="#foo">
68 <img src="assets/clippy.svg" alt="Copy to clipboard"> 62 <img src="assets/clippy.svg" alt="Copy to clipboard">
69 </button> 63 </button>
70 ``` 64 ```
71   65  
72 ### Cut text from another element 66 ### Cut text from another element
73   67  
74 Additionally, you can define a `data-clipboard-action` attribute to specify if you want to either `copy` or `cut` content. 68 Additionally, you can define a `data-clipboard-action` attribute to specify if you want to either `copy` or `cut` content.
75   69  
76 If you omit this attribute, `copy` will be used by default. 70 If you omit this attribute, `copy` will be used by default.
77   71  
78 <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> 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>
79   73  
80 ```html 74 ```html
81 <!-- Target --> 75 <!-- Target -->
82 <textarea id="bar">Mussum ipsum cacilds...</textarea> 76 <textarea id="bar">Mussum ipsum cacilds...</textarea>
83   77  
84 <!-- Trigger --> 78 <!-- Trigger -->
85 <button class="btn" data-clipboard-action="cut" data-clipboard-target="#bar"> 79 <button class="btn" data-clipboard-action="cut" data-clipboard-target="#bar">
86 Cut to clipboard 80 Cut to clipboard
87 </button> 81 </button>
88 ``` 82 ```
89   83  
90 As you may expect, the `cut` action only works on `<input>` or `<textarea>` elements. 84 As you may expect, the `cut` action only works on `<input>` or `<textarea>` elements.
91   85  
92 ### Copy text from attribute 86 ### Copy text from attribute
93   87  
94 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. 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.
95   89  
96 <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> 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>
97   91  
98 ```html 92 ```html
99 <!-- Trigger --> 93 <!-- Trigger -->
100 <button class="btn" data-clipboard-text="Just because you can doesn't mean you should — clipboard.js"> 94 <button class="btn" data-clipboard-text="Just because you can doesn't mean you should — clipboard.js">
101 Copy to clipboard 95 Copy to clipboard
102 </button> 96 </button>
103 ``` 97 ```
104   98  
105 ## Events 99 ## Events
106   100  
107 There are cases where you'd like to show some user feedback or capture what has been selected after a copy/cut operation. 101 There are cases where you'd like to show some user feedback or capture what has been selected after a copy/cut operation.
108   102  
109 That's why we fire custom events such as `success` and `error` for you to listen and implement your custom logic. 103 That's why we fire custom events such as `success` and `error` for you to listen and implement your custom logic.
110   104  
111 ```js 105 ```js
112 var clipboard = new Clipboard('.btn'); 106 var clipboard = new Clipboard('.btn');
113   107  
114 clipboard.on('success', function(e) { 108 clipboard.on('success', function(e) {
115 console.info('Action:', e.action); 109 console.info('Action:', e.action);
116 console.info('Text:', e.text); 110 console.info('Text:', e.text);
117 console.info('Trigger:', e.trigger); 111 console.info('Trigger:', e.trigger);
118   112  
119 e.clearSelection(); 113 e.clearSelection();
120 }); 114 });
121   115  
122 clipboard.on('error', function(e) { 116 clipboard.on('error', function(e) {
123 console.error('Action:', e.action); 117 console.error('Action:', e.action);
124 console.error('Trigger:', e.trigger); 118 console.error('Trigger:', e.trigger);
125 }); 119 });
126 ``` 120 ```
127   121  
128 For a live demonstration, open this [site](https://clipboardjs.com/) and just your console :) 122 For a live demonstration, open this [site](https://clipboardjs.com/) and just your console :)
129   123  
130 ## Advanced Options 124 ## Advanced Options
131   125  
132 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. 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.
133   127  
134 For instance, if you want to dynamically set a `target`, you'll need to return a Node. 128 For instance, if you want to dynamically set a `target`, you'll need to return a Node.
135   129  
136 ```js 130 ```js
137 new Clipboard('.btn', { 131 new Clipboard('.btn', {
138 target: function(trigger) { 132 target: function(trigger) {
139 return trigger.nextElementSibling; 133 return trigger.nextElementSibling;
140 } 134 }
141 }); 135 });
142 ``` 136 ```
143   137  
144 If you want to dynamically set a `text`, you'll return a String. 138 If you want to dynamically set a `text`, you'll return a String.
145   139  
146 ```js 140 ```js
147 new Clipboard('.btn', { 141 new Clipboard('.btn', {
148 text: function(trigger) { 142 text: function(trigger) {
149 return trigger.getAttribute('aria-label'); 143 return trigger.getAttribute('aria-label');
150 } 144 }
151 }); 145 });
152 ``` 146 ```
-   147  
-   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 ```
153   155  
154 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. 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.
155   157  
156 ```js 158 ```js
157 var clipboard = new Clipboard('.btn'); 159 var clipboard = new Clipboard('.btn');
158 clipboard.destroy(); 160 clipboard.destroy();
159 ``` 161 ```
160   162  
161 ## Browser Support 163 ## Browser Support
162   164  
163 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. 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.
164   166  
165 | <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"> | 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"> |
166 |:---:|:---:|:---:|:---:|:---:|:---:| 168 |:---:|:---:|:---:|:---:|:---:|:---:|
167 | 42+ ✔ | 12+ ✔ | 41+ ✔ | 9+ ✔ | 29+ ✔ | 10+ ✔ | 169 | 42+ ✔ | 12+ ✔ | 41+ ✔ | 9+ ✔ | 29+ ✔ | 10+ ✔ |
168   170  
169 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. 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.
170   172  
171 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. 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  
-   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/).
172   180  
173 ## License 181 ## License
174   182  
175 [MIT License](http://zenorocha.mit-license.org/) © Zeno Rocha 183 [MIT License](http://zenorocha.mit-license.org/) © Zeno Rocha
176   184