224 lines
6.5 KiB
Markdown
224 lines
6.5 KiB
Markdown
# Circles
|
|
|
|
|
|
|
|
Lightweight JavaScript library that generates circular graphs in SVG. Now with animation.
|
|
|
|
### Usage
|
|
|
|
Include the `circles.js` or `circles.min.js` file in your HTML file. There are no dependencies.
|
|
|
|
Create a placeholder div in your HTML:
|
|
|
|
```html
|
|
<div class="circle" id="circles-1"></div>
|
|
```
|
|
|
|
Create a graph by calling, the id should match id of the placeholder `<div>`:
|
|
|
|
```js
|
|
var myCircle = Circles.create({
|
|
id: 'circles-1',
|
|
radius: 60,
|
|
value: 43,
|
|
maxValue: 100,
|
|
width: 10,
|
|
text: function(value){return value + '%';},
|
|
colors: ['#D3B6C6', '#4B253A'],
|
|
duration: 400,
|
|
wrpClass: 'circles-wrp',
|
|
textClass: 'circles-text',
|
|
valueStrokeClass: 'circles-valueStroke',
|
|
maxValueStrokeClass: 'circles-maxValueStroke',
|
|
styleWrapper: true,
|
|
styleText: true
|
|
});
|
|
```
|
|
|
|
where
|
|
|
|
* `id` - the DOM element that will hold the graph
|
|
* `radius` - the radius of the circles
|
|
* `value` - init value of the circle (optional, defaults to 0)
|
|
* `maxValue` - maximum value of the circle (optional, defaults to 100)
|
|
* `width` - the width of the ring (optional, has value 10, if not specified)
|
|
* `colors` - an array of colors, with the first item coloring the full circle (optional, it will be `['#EEE', '#F00']` if not specified) Can also be an rgba() value (example: ['rgba(255,255,255,0.25)', 'rgba(125,125,125,0.5)'])
|
|
* `duration` - value in ms of animation's duration; defaults to 500; if 0 or `null` is passed, the animation will not run.
|
|
* `wrpClass` - class name to apply on the generated element wrapping the whole circle.
|
|
* `textClass` - class name to apply on the generated element wrapping the text content.
|
|
* `valueStrokeClass` - class name to apply on the SVG path element which for the `value` amount.
|
|
* `maxValueStrokeClass` - class name to apply on the SVG path element which for the `maxValue` amount.
|
|
* `styleWrapper` - whether or not to add inline styles to the wrapper element (defaults to true)
|
|
* `styleText` - whether or not to add inline styles to the text (defaults to true)
|
|
* `text` - the text to display at the center of the graph (optional, the current "htmlified" value will be shown). If `null` or an empty string, no text will be displayed. It can also be a function: the returned value will be the displayed text like in the examples below:
|
|
|
|
```js
|
|
// Example 1
|
|
function(currentValue) {
|
|
return '$'+currentValue;
|
|
}
|
|
// Example 2
|
|
function() {
|
|
return this.getPercent() + '%';
|
|
}
|
|
```
|
|
|
|
|
|
### Install with grunt
|
|
|
|
1. Get the library
|
|
2. Install all the dependencies, run `npm install`
|
|
3. Once you have the dependencies installed, run `grunt` from the project directory. This will run the default grunt task which will minify `circles.js` to `circles.min.js`
|
|
|
|
|
|
### API
|
|
|
|
```js
|
|
myCircle.updateRadius(Number radius)
|
|
```
|
|
|
|
Regenerates the circle with the given `radius` (see `spec/responsive.html` for an example on how to create a responsive circle).
|
|
|
|
```js
|
|
myCircle.updateWidth(Number width)
|
|
```
|
|
|
|
Regenerates the circle with the given `width`
|
|
|
|
```js
|
|
myCircle.updateColors(Array colors)
|
|
```
|
|
|
|
Change `colors` used to draw the circle.
|
|
|
|
```js
|
|
myCircle.update(Number value [, Number duration])
|
|
```
|
|
|
|
Set the value of the circle to `value`.
|
|
Animation will take `duration` ms to execute. If no `duration` is given, default duration set in constructor will be used.
|
|
If you don't want animation, set `duration` to 0.
|
|
|
|
```js
|
|
myCircle.update(Boolean force)
|
|
```
|
|
|
|
Force the redrawing of the circle if `force` is set to **true**. Do nothing otherwise.
|
|
|
|
```js
|
|
myCircle.getPercent()
|
|
```
|
|
|
|
Returns the percentage value of the circle, based on its current value and its max value.
|
|
|
|
```js
|
|
myCircle.getValue()
|
|
```
|
|
|
|
Returns the value of the circle.
|
|
|
|
```js
|
|
myCircle.getMaxValue()
|
|
```
|
|
|
|
Returns the max value of the circle.
|
|
|
|
```js
|
|
myCircle.getValueFromPercent(Number percentage)
|
|
```
|
|
|
|
Returns the corresponding value of the circle based on its max value and given `percentage`.
|
|
|
|
```js
|
|
myCircle.htmlifyNumber(Number number[, integerPartClass, decimalPartClass])
|
|
```
|
|
|
|
Returned HTML representation of given `number` with given classes names applied on tags.
|
|
Default value of `integerPartClass` is **circles-integer**.
|
|
Default value of `decimalPartClass` is **circles-decimals**.
|
|
|
|
### Styles
|
|
|
|
The styles have been specified inline to avoid external dependencies. But they can be overriden via CSS easily, being simply HTML elements.
|
|
|
|
To help with this, a few CSS classes have been exposed:
|
|
|
|
* `circles-wrp` - the element wrapping the whole circle
|
|
* `circles-text` - the element wrapping text content
|
|
* `circles-integer` - the element wrapping the text before the dot
|
|
* `circles-decimals` - the element wrapping the decimal places
|
|
|
|
You can override these classes by sending properties `wrpClass` and/or `textClass` to the constructor.
|
|
|
|
|
|
### Tests
|
|
|
|
Tests can be run with [karma](http://karma-runner.github.io/0.12/index.html):
|
|
|
|
```shell
|
|
karma start
|
|
```
|
|
|
|
or [grunt](http://gruntjs.com):
|
|
|
|
```shell
|
|
grunt jasmine
|
|
```
|
|
|
|
### Examples
|
|
|
|
* [index.html](https://github.com/lugolabs/circles/blob/master/spec/index.html) - Overall functionality
|
|
* [responsive.html](https://github.com/lugolabs/circles/blob/master/spec/responsive.html) - Making circles responsive
|
|
* [viewport.html](https://github.com/lugolabs/circles/blob/master/spec/viewport.html) - Animate the circles when in viewport
|
|
|
|
|
|
### Compatibility
|
|
|
|
Browsers that support SVG.
|
|
|
|
**Desktop**
|
|
* Firefox 3+
|
|
* Chrome 4+
|
|
* Safari 3.2+
|
|
* Opera 9+
|
|
* IE9 +
|
|
|
|
**Mobile**
|
|
* iOS Safari 3.2+
|
|
* Android Browser 3+
|
|
* Opera Mobile 10+
|
|
* Chrome for Android 18+
|
|
* Firefox for Android 15+
|
|
|
|
### Contributors
|
|
|
|
* Artan Sinani
|
|
* [Adrien Guéret](https://github.com/adrien-gueret)
|
|
* [radoslawhryciow](https://github.com/radoslawhryciow)
|
|
* [Roman Salnikov](https://github.com/RSalo)
|
|
* [webal](https://github.com/webal)
|
|
* [Kieran](https://github.com/kieranajp)
|
|
|
|
|
|
### Inspirations
|
|
|
|
Code and ideas borrowed by:
|
|
|
|
* [Highcharts](http://highcharts.com)
|
|
* Wout Fierens's [svg.js](http://svgjs.com)
|
|
|
|
|
|
### Licence
|
|
|
|
Circles is licensed under the terms of the MIT License.
|
|
|
|
### Changelog
|
|
|
|
* 0.0.6 Make inline styles optional.
|
|
* 0.0.5 Rethink a bit the way the library is working + add some public methods.
|
|
* 0.0.4 Exposes `generate(radius)` to regenerate the circle, opening it to responsiveness.
|
|
* 0.0.3 Allow adding extra text to the graph (issue 3).
|
|
Round integers during animation.
|
|
* 0.0.2 Add animation.
|
|
* 0.0.1 First release.
|