1# c3chart Plugin for DokuWiki #
2
3The `c3chart` plugin for DokuWiki makes it easy to insert interactive data charts rendered by [C3.js](http://c3js.org/), which is powered by the popular [D3.js library](http://d3js.org/).
4
5This plugin accepts the same JavaScript object that C3 takes to generate a chart. Any chart describable by a static JavaScript object is supported. All types of charts natively supported by C3 can be rendered, such as line/bar/pie/donut charts, as well as scatter plots.
6
7Here are a few screenshots of the rendered charts:
8
9![Line chart](http://i.imgur.com/gZtX5eo.png)
10
11![Stacked bar chart](http://i.imgur.com/MvNROm7.png)
12
13![Pie chart](http://i.imgur.com/Fax0X0S.png)
14
15For more examples, check the [C3 Examples](http://c3js.org/examples.html).
16
17
18## Installation ##
19The latest ZIP package of this plugin can be downloaded [here](https://github.com/jasonxunxu/dokuwiki-plugin-c3chart/archive/master.zip).
20
21If you install this plugin manually, make sure it is installed in `lib/plugins/c3chart/` - if the folder is called different it may not work.
22
23Please refer to the [DokuWiki document](http://www.dokuwiki.org/plugins) for additional info on how to install plugins in DokuWiki.
24
25## Usage ##
26This plugin accepts the same JavaScript object that the `generate()` function of C3.js takes to render a chart. To include a chart in your DokuWiki page, simply wrap such a JavaScript object with a `<c3>` tag.
27
28To render the pie chart shown above:
29```
30<c3>
31{
32  data: {
33    columns: [
34      ['data1', 30],
35      ['data2', 120],
36    ],
37    type : 'pie',
38  }
39}
40</c3>
41```
42
43The outermost braces can be omitted, so this is also valid (and recommended):
44```
45<c3>
46  // some comment
47  data: {
48    columns: [
49      ['data1', 30], /* more comment */
50      ['data2', 120],
51    ],
52    type : 'pie',
53  }
54</c3>
55```
56Also note that you can include comments in the snippet, both styles (`//` and `/* */`) are supported.
57
58The major restriction is that the JavaScript object must be **static**, i.e. it cannot include function calls or function expressions, for security reasons.
59
60## Options ##
61The `<c3>` tag can carry optional attributes to customize the appearance of the chart. The attributes are separated by spaces, each specified in the format of `name=value`. Valid attributes are:
62
63| Name     | Description |
64|:--------:|:----------- |
65| `width`  | Width of the chart, specified in CSS format, e.g. 50% or 320px. |
66| `height` | Height of the chart, in the same format as `width`. |
67| `align`  | Chart alignment, can be `left`, `right` or `center`. |
68
69For instance to make your chart occupying half width of its container and floated to the right:
70```
71<c3 width=50% align=right>
72  data: {
73    ...
74  }
75</c3>
76```
77
78## Configuration ##
79The plugin can be configured in the DokuWiki Configuration Manager, with following variables:
80
81| Name     | Description |
82|:--------:|:----------- |
83| `url_*`  | URL of the dependent libraries. A relative path means that the URL is relative to the `assets` directory of the installed plugin. |
84| `width`  | Default width of charts. |
85| `height` | Default height of charts. |
86| `align`  | Default alignment of charts. |
87
88
89## License ##
90Copyright (C) Jason Xun Xu <dev (a) jasonxu (.) net>
91
92This program is free software; you can redistribute it and/or modify
93it under the terms of the GNU General Public License as published by
94the Free Software Foundation; version 2 of the License
95
96This program is distributed in the hope that it will be useful,
97but WITHOUT ANY WARRANTY; without even the implied warranty of
98MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
99GNU General Public License for more details.
100
101See the COPYING file in your DokuWiki folder for details.
102
103