supportcandy / asset / libs / jquery-circle-progress / README.md

README.md in SupportCandy – AI Customer Support Ticket System & Live Chatbot Agent 3.4.3, at asset/libs/jquery-circle-progress/README.md

303 lines 10.7 KB

Raw Download Zip

1	jquery-circle-progress
2	======================
3
4	[](https://travis-ci.org/kottenator/jquery-circle-progress![Build status](https://travis-ci.org/kottenator/jquery-circle-progress.svg?branch=master)](https://travis-ci.org/kottenator/jquery-circle-progress](https://travis-ci.org/kottenator/jquery-circle-progress)
5	[](https://bower.io/search/?q=jquery-circle-progress![Bower version](https://img.shields.io/bower/v/jquery-circle-progress.svg?maxAge=2592000)](https://bower.io/search/?q=jquery-circle-progress](https://bower.io/search/?q=jquery-circle-progress)
6	[](https://www.npmjs.com/package/jquery-circle-progress![NPM version](https://img.shields.io/npm/v/jquery-circle-progress.svg?maxAge=2592000)](https://www.npmjs.com/package/jquery-circle-progress](https://www.npmjs.com/package/jquery-circle-progress)
7
8	jQuery Plugin to draw animated circular progress bars like this:
9
10	![](http://i.imgur.com/zV5VUQG.png)
11
12	Check out [](http://kottenator.github.io/jquery-circle-progress/more examples](http://kottenator.github.io/jquery-circle-progress/](http://kottenator.github.io/jquery-circle-progress/)! Or maybe the crazy [](http://jsbin.com/vatuza/5/one](http://jsbin.com/vatuza/5/](http://jsbin.com/vatuza/5/)?
13
14	Install
15	-------
16
17	Make your choice:
18
19	* Download [](https://github.com/kottenator/jquery-circle-progress/releaseslatest GitHub release](https://github.com/kottenator/jquery-circle-progress/releases](https://github.com/kottenator/jquery-circle-progress/releases)
20	* `bower install jquery-circle-progress`
21	* `npm install jquery-circle-progress`
22
23	Usage
24	-----
25
26	```html
27	<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
28	<script src="jquery-circle-progress/dist/circle-progress.js"></script>
29
30	<div id="circle"></div>
31
32	<script>
33	$('#circle').circleProgress({
34	value: 0.75,
35	size: 80,
36	fill: {
37	gradient: ["red", "orange"]
38	}
39	});
40	</script>
41	```
42
43	If you use AMD or CommonJS with some JS bundler - see the [](#umdUMD section](#umd](#umd) below.
44
45	Options
46	-------
47
48	Specify options like in example above.
49
50	\| Option \| Description \|
51	\| ---- \| ---- \|
52	\| value \| This is the only required option. It should be from `0.0` to `1.0` <br> Default: `0` \|
53	\| size \| Size of the circle / canvas in pixels <br> Default: `100` \|
54	\| startAngle \| Initial angle (for `0` value) <br> Default: `-Math.PI` \|
55	\| reverse \| Reverse animation and arc draw <br> Default: `false` \|
56	\| thickness \| Width of the arc. By default it's automatically calculated as 1/14 of `size` but you may set your own number <br> Default: `"auto"` \|
57	\| lineCap \| Arc line cap: `"butt"`, `"round"` or `"square"` - [read more](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D.lineCap) <br> Default: `"butt"`
58	\| fill \| The arc fill config. You may specify next: <br>- `"#ff1e41"` <br>- `{ color: "#ff1e41" }` <br>- `{ color: 'rgba(255, 255, 255, .3)' }` <br>- `{ gradient: ["red", "green", "blue"] }` <br>- `{ gradient: [["red", .2], ["green", .3], ["blue", .8]] }` <br>- `{ gradient: [ ... ], gradientAngle: Math.PI / 4 }` <br>- `{ gradient: [ ... ], gradientDirection: [x0, y0, x1, y1] }` <br>- `{ image: "http://i.imgur.com/pT0i89v.png" }`<br>- `{ image: imageInstance }`<br>- `{ color: "lime", image: "http://i.imgur.com/pT0i89v.png" }` <br> Default: `{ gradient: ["#3aeabb", "#fdd250"] }` \|
59	\| emptyFill \| Color of the "empty" arc. Only a color fill supported by now <br> Default: `"rgba(0, 0, 0, .1)"` \|
60	\| animation \| Animation config. See [](http://api.jquery.com/animate/jQuery animations](http://api.jquery.com/animate/](http://api.jquery.com/animate/). <br> You may also set it to `false` <br> Default: `{ duration: 1200, easing: "circleProgressEase" }` <br> `"circleProgressEase"` is just a ease-in-out-cubic easing \|
61	\| animationStartValue \| Default animation starts at `0.0` and ends at specified `value`. Let's call this direct animation. If you want to make reversed animation then you should set `animationStartValue` to `1.0`. Also you may specify any other value from `0.0` to `1.0` <br> Default: `0.0`
62	\| insertMode \| Canvas insertion mode: append or prepend it into the parent element? <br> Default: `"prepend"` \|
63
64	From version `1.1.3` you can specify any config option as HTML `data-` attribute.
65
66	It will work only on init, i.e. after the widget is inited you may update its properties only via `.circleProgress({/.../})` method. `data-` attributes will be ignored.
67
68	Also, object options like `"fill"` or `"animation"` should be valid JSON (and don't forget about HTML-escaping):
69
70	```html
71	<div
72	class="circle"
73	data-value="0.9"
74	data-size="60"
75	data-thickness="20"
76	data-animation-start-value="1.0"
77	data-fill="{
78	"color": "rgba(0, 0, 0, .3)",
79	"image": "http://i.imgur.com/pT0i89v.png"
80	}"
81	data-reverse="true"
82	></div>
83	```
84
85	Events
86	------
87
88	\| Event \| Description \| Handler \|
89	\| ---- \| ---- \| ---- \|
90	\| `circle-inited` \| Triggered on init or re-init. \| `function(event)`: <br>- `event` - jQuery event \|
91	\| `circle-animation-start` \| Triggered once the animation is started. \| `function(event)`: <br>- `event` - jQuery event \|
92	\| `circle-animation-progress` \| Triggered on each [](http://api.jquery.com/animate/#stepanimation tick](http://api.jquery.com/animate/#step](http://api.jquery.com/animate/#step). \| `function(event, animationProgress, stepValue)`: <br>- `event` - jQuery event <br>- `animationProgress` - from `0.0` to `1.0` <br>- `stepValue` - current step value: from `0.0` to `value` \|
93	\| `circle-animation-end` \| Triggered once the animation is finished. \| `function(event)`: <br>- `event` - jQuery event \|
94
95	Browsers support
96	----------------
97
98	The library uses `<canvas>` which is supported by all modern browsers (including mobile browsers)
99	and Internet Explorer 9+ ([](http://caniuse.com/#search=canvasCan I Use](http://caniuse.com/#search=canvas](http://caniuse.com/#search=canvas)).
100
101	I haven't implemented any fallback / polyfill for unsupported browsers yet
102	(i.e. for Internet Explorer 8 and older / misc browsers).
103
104	UMD
105	---
106
107	I use [](https://github.com/umdjs/umd/blob/d31bb6ee7098715e019f52bdfe27b3e4bfd2b97e/templates/jqueryPlugin.jsUMD template for jQuery plugin](https://github.com/umdjs/umd/blob/d31bb6ee7098715e019f52bdfe27b3e4bfd2b97e/templates/jqueryPlugin.js](https://github.com/umdjs/umd/blob/d31bb6ee7098715e019f52bdfe27b3e4bfd2b97e/templates/jqueryPlugin.js) which combines three things:
108
109	* works fine with _browser globals_
110	* works fine with AMD
111	* works fine with CommonJS
112
113	### Browser globals
114
115	```html
116	<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
117	<script src="jquery-circle-progress/dist/circle-progress.js"></script>
118	<script>
119	$('#circle').circleProgress({
120	value: 0.75,
121	});
122	</script>
123	```
124
125	### AMD
126
127	Assuming that you have `jquery`, `jquery-circle-progress` and `requirejs` in `libs/` directory:
128
129	```html
130	<script src="libs/requirejs/require.js"></script>
131	<script>
132	requirejs.config({
133	paths: {
134	'jquery': 'libs/jquery/dist/jquery', // 'jquery' path is required - 'jquery-circle-progress' requires it
135	'jquery-circle-progress': 'libs/jquery-circle-progress/dist/circle-progress' // and this one is for your convenience
136	}
137	});
138	requirejs(['jquery', 'jquery-circle-progress'], function($) {
139	$('#circle').circleProgress({
140	value: 0.75
141	});
142	});
143	</script>
144	```
145
146	You can [](http://requirejs.org/docs/api.htmlconfigure RequireJS](http://requirejs.org/docs/api.html](http://requirejs.org/docs/api.html) as you wish, just make `'jquery'` dependency reachable.
147
148	### CommonJS
149
150	```js
151	// script.js
152	require('jquery-circle-progress');
153	var $ = require('jquery');
154	$('#circle').circleProgress({
155	value: 0.75
156	});
157	```
158
159	```sh
160	some-js-bundler < script.js > script.bundle.js
161	```
162
163	```html
164	<script src="script.bundle.js"></script>
165	```
166
167	You can use any JS bundler ([](https://webpack.github.io/Webpack](https://webpack.github.io/](https://webpack.github.io/), [](http://browserify.org/Browserify](http://browserify.org/](http://browserify.org/), etc) - no specific configuration required.
168
169	API
170	---
171
172	### Get/set value
173
174	Get it:
175
176	```js
177	$('.circle').circleProgress({ value: 0.5 });
178	var value = $('.circle').circleProgress('value'); // 0.5
179	```
180
181	It will return the first item's value (by first I mean when `$('.circle').length >= 1`).
182	It works only if the widget is already inited. Raises an error otherwise.
183
184	Set it:
185
186	```js
187	$('.circle').circleProgress('value', 0.75); // set value to 0.75 & animate the change
188	```
189
190	It will update all selected items value and animate the change.
191	It doesn't redraw the widget - it updates the value & animates the changes.
192	For example, it may be an AJAX loading indicator, which shows the loading progress.
193
194	### Get `<canvas>`
195
196	```js
197	$('.circle').circleProgress({ value: 0.5 });
198	var canvas = $('.circle').circleProgress('widget');
199	```
200
201	It will return the first item's `<canvas>` (by first I mean when `$('.circle').length >= 1`).
202	It works only if the widget is already inited. Raises an error otherwise.
203
204	### Get `CircleProgress` instance
205
206	```js
207	var instance = $('#circle').data('circle-progress');
208	```
209
210	### Redraw existing circle
211
212	```js
213	$('#circle').circleProgress({ value: 0.5, fill: { color: 'orange' }});
214	$('#circle').circleProgress('redraw'); // use current configuration and redraw
215	$('#circle').circleProgress(); // alias for 'redraw'
216	$('#circle').circleProgress({ size: 150 }); // set new size and redraw
217	```
218
219	It works only if the widget is already inited. Raises an error otherwise.
220
221	### Change default options
222
223	```js
224	$.circleProgress.defaults.size = 50;
225	```
226
227	FAQ
228	---
229
230	<dl>
231	<dt>How to start the animation only when the circle appears in browser's view (on scrolling)?
232	<dd>Here is <a href="https://github.com/kottenator/jquery-circle-progress/issues/8">my proposed solution</a>.
233	<dt>How to make the size flexible?
234	<dd>E.g. for responsive design, you can do it <a href="https://github.com/kottenator/jquery-circle-progress/issues/17">in the following way</a>.
235	<dt>What if I need it to run in IE8?
236	<dd>There is no full-feature support for IE8 (actually, I didn't imlpement IE8 support at all). But you may follow <a href="https://github.com/kottenator/jquery-circle-progress/issues/35">my recommendations</a>.
237	<dt>How to stop the animation?
238	<dd>Here is <a href="https://github.com/kottenator/jquery-circle-progress/issues/37">what you can do</a>.
239	<dt>Can I handle "click" event?
240	<dd>It's not in the "core" but you can use <a href="http://output.jsbin.com/fetequ/5">my example of mouse/touch events handling</a>.
241	<dt>May I customize the shape somehow?
242	<dd>It's a bit "tricky" but possible. Here is <a href="https://github.com/kottenator/jquery-circle-progress/wiki/Custom-layouts">my little collection</a>.
243	</dl>
244
245	Development
246	-----------
247
248	### Install
249
250	```sh
251	git clone [email protected]:kottenator/jquery-circle-progress.git
252	npm install
253	```
254
255	### Modify
256
257	You need to update `dist/circle-progress.min.js` after any change to `dist/circle-progress.js`:
258
259	```sh
260	npm run build-min
261	```
262
263	If you're using one of JetBrains IDEs - you can configure a File Watcher.
264	It's also possible to use some CLI tool like [](https://facebook.github.io/watchman/Watchman](https://facebook.github.io/watchman/](https://facebook.github.io/watchman/).
265
266	### Test
267
268	```sh
269	npm test
270	```
271
272	SauceLabs:
273
274	```sh
275	export SAUCE_USERNAME=...
276	export SAUCE_ACCESS_KEY=...
277	export BUILD_NUMBER=...
278	npm test -- karma-saucelabs.conf.js
279	```
280
281	### Build docs
282
283	The API docs are not complete yet but you can build them:
284
285	```sh
286	npm run build-docs
287	```
288
289	They will be generated in `docs/api/`.
290
291	### Release new version
292
293	* finalize the code
294	* update the version in `package.json`, `bower.json` and `dist/circle-progress.js` docstring
295	* update min dist: `npm run build-min`
296	* update `docs/index.html` - link to the latest dist version _(which doesn't exist yet)_
297	* push the changes to `master` branch
298	* release on Bower: just create a Git tag (e.g.): `git tag v1.2.3 && git push --tags`
299	* release on GitHub - add release notes to the Git tag
300	* release on NPM: `npm publish`, but be aware:
301
302	> Once a package is published with a given name and version, that specific name and version combination can never be used again - [](https://docs.npmjs.com/cli/publishNPM docs](https://docs.npmjs.com/cli/publish](https://docs.npmjs.com/cli/publish)
303