====== Dokuwiki Charter Plugin ======

===== Description =====

The Dokuwiki Charter Plugin provides a syntax for drawing highly customizable charts using the [[http://pchart.sourceforge.net/|pChart library]]. Currently line, curve, bar and pie graphs are supported.

In case you come across any bugs in this plugin, please don't hesitate to [[http://flyspray.foosel.org/index.php?do=newtask&project=12|report them]].

The Git repository of the plugin can be found [[http://github.com/foosel/dokuwiki-charter|at Github]].

===== Dependencies =====

In order for the pChart library and therefore the charter plugin to work, you need to have [[http://php.net/gd|GDlib support (with Freetype compiled in) enabled in your PHP installation]]. 

===== Acknowledgements =====

The charter plugin bundles the [[http://pchart.sourceforge.net/|pChart library]] and the [[http://www.gnome.org/fonts/|Bitstream Vera font family]]. Credit goes to the respective authors.

===== Updates =====

**Last updated:** 2008/12/21

  * 2008/12/21:
    * Initial release

===== Syntax =====

Graph definitions are enclosed in ''%%<charter>...</charter>%%'' blocks. These blocks consist of two parts: parameters and data, which is separated from the parameters by an empty line. Parameters are name/value pairs separated by an ''=''. Data has to be CSV formatted((the charter plugin only understands very basic CSV, with the only accepted delimiter being a comma and no support for quoted values exists)). Example:

<code>
<charter>
param1 = value
param2 = value

1, 2, 3, 4, 5
2, 3, 4, 5, 1
3, 4, 5, 1, 2
</charter>
</code>

Using parameters, one can customize the generated graph, including size, title, type, colors and a multitude of other settings. You do not have to use all these settings though, the internal default values are very suitable for the generation of quick nice looking graphs already.

Below you can find a detailed list of all settings available. For examples of the application of these settings, please see the [[#examples|examples section]] further down.

Generated graphs are automatically saved as media files (PNG images to be exact) in the same namespace as the page they belong to. The chosen filename is either "''chart-<title>.png''" or "''chart-notitle_<md5sum of the chart definition>.png''", depending on whether a title was defined for the chart or not. It thus is important to make sure to not have more than one equally titled chart per namespace.

==== Basic setup ====

These are the only settings you should set on any graph you generate.

^ Parameter ^ Description ^
| title | The title of the graph to be displayed. Defaults to an empty string. |
| size | The size of the generated graph. Format is ''<width>x<height>''. Defaults to 600px width and 300px height. |
| align | Alignment of the generated graph image. Can be either of ''left'', ''right'' or ''center''. Defaults to ''left''. |
| type | Type of the graph to generate. Supported types are ''line'', ''lineFilled'', ''cubic'', ''cubicFilled'', ''bar'', ''barStacked'', ''barOverlayed'', ''pie'', ''pie3d'', ''pieExploded''. Defaults to ''line''. |

==== Font settings ====

All font settings must be formatted as ''<fontfile>@<size>'' where fontfile is the case sensitive name of a truetype font file located at ''charter/lib/fonts'' and size an unsigned integer denoting the size of the font in pixels.

^ Parameter ^ Description ^
| fontTitle | The font to use for the title. Format is <fontfile>@<size>. Defaults to Bitstream Vera Sans Bold, size 10. |
| fontLegend | The font to use for legends and graph labels. Format is <fontfile>@<size>. Defaults to Bitstream Vera Sans, size 8. |
| fontDefault | The font to use for everything else (axis labels, tick labels, ...). Format is <fontfile>@<size>. Defaults to Bitstream Vera Sans, size 8. |

==== Color settings ====

All color settings except the gradients must be formatted as HTML RGB specification, e.g. ''#RRGGBB'' or ''#RGB''. The leading ''#'' is optional.

^ Parameter ^ Description ^
| bgcolor | Background color of the whole graph. Defaults to ''#fafafa'' |
| legendColor | Background color of legend box. Defaults to ''#fafafa'' |
| graphColor | Background color of the graph area. Defaults to ''#ffffff'' (transparent, not white!). |
| titleColor | Foreground color of the title. Defaults to ''#000000'' |
| scaleColor | Foreground color of the scale. Defaults to ''#969696'' |
| shadowColor | Color of the drop shadow. Defaults to ''#c8c8c8'' (suitable for pie charts, for line or curve shadows i recommend ''#333333'') |
| bggradient | Gradient definition of the gradient to use as background for the whole chart. Format ist ''<RGB>@<shades>'' where ''RGB'' is once again an HTML RGB color definition and ''shades'' the number of color steps for the gradient to generate based on this color. Defaults to not set. |
| graphGradient | Gradient definition of the gradient to use as background for the graph area. Format ist ''<RGB>@<shades>'' where ''RGB'' is once again an HTML RGB color definition and ''shades'' the number of color steps for the gradient to generate based on this color. Defaults to not set. |

==== Descriptional settings ====

In settings in which you refer to your declared data rows, you can do so by their number. The first row is ''1'', the second is ''2'' etc. This is important for ''labelSerie'' and ''graphLabels''.

^ Parameter ^ Description ^
| XAxisName | Sets the name of the X-Axis. Defaults to not set. |
| XAxisUnit | Sets the unit of the X-Axis, which gets automatically appended to each tick's labels. Defaults to not set. |
| XAxisFormat | Sets the format of the X-Axis. This can be any of ''number'', ''date'', ''time'', ''metric'' or ''currency'' -- see below for a description of those. Defaults to ''number''. |
| YAxisName | Sets the name of the Y-Axis. Defaults to not set. |
| YAxisUnit | Sets the unit of the Y-Axis, which gets automatically appended to each tick's labels. Defaults to not set. |
| YAxisFormat | Sets the format of the Y-Axis. This can be any of ''number'', ''date'', ''time'', ''metric'' or ''currency'' -- see below for a description of those. Defaults to ''number''. |
| labelSerie | Which data row to use for X-Axis tick labels. I recommend to always use the last row for this purpose, as the underlying pChart library seems to have an issue when using the first. Defaults not not set. |
| legendEntries | Descriptions of the plotted data rows to be used in the legend. Formatted as a comma separated list. Should be as many entries as there are rows plotted. Defaults to not set. |
| graphLabels | A comma separated list of labels you wish to add to your graph to let important data points stand out. Each item has to be of the format ''<Serie-No>|<X-Value>|<Description>'' where ''Serie-No'' is the number of the data row to which to attach the label (starting at 1), ''X-Value'' is the value on the X-Axis to which to attach the label (starting at 0, or if you defined a ''labelSerie'' the corresponding value from this row) and ''Description'' is the description to show in the label. Defaults to not set. |

Documentation for axis formats:

<blockquote>
  * **number** -- used by defaults
  * **time** -- amount of seconds will be displayed as HH:MM:SS
  * **date** -- unix timestamp will be displayed as a date
  * **metric** -- number that will be displayed with k/m/g units
  * **currency** -- currency with custom unit
<cite>[[http://pchart.sourceforge.net/documentation.php?topic=pData#|pChart documentation]]</cite>
</blockquote>

==== Pie chart settings ====

Special settings only applying to pie charts. Boolean values can be ''true'', ''on'', ''1'' for true and ''false'', ''off'', ''0'' for false.

^ Parameter ^ Description ^
| pieLabels | Boolean value setting whether to show labels in the pie chart. Defaults to ''true''. |
| piePercentages | Boolean value setting whether to show percentages in the pie chart. Defaults to ''true''. |
| pieExploded | Boolean value setting whether to draw the pie chart in exploded state. Defaults to ''false''. |

When drawing pie charts, there must be only one data serie, or two if one of them is declared as ''labelSerie''.

==== Other settings ====

Boolean values can be ''true'', ''on'', ''1'' for true and ''false'', ''off'', ''0'' for false.

^ Parameter ^ Description ^
| thresholds | Thresholds to plot into the diagram. Format is a comma-separated list of numeric values denoting the Y-value at which to draw the threshold. Defaults to not set. |
| palette | Color palette to use for the graph. Format is a string containing the filename of a palette file in ''charter/lib/palettes'' without the trailing ''.txt'' extension. Defaults to not set (and thus the use of the internal palette). |
| legend | Boolean value setting whether to show the legend. Defaults to ''true''. |
| grid | Boolean value setting whether to draw the grid. Defaults to ''true''. |
| alpha | Alpha value to use for drawing grid, bar charts and filled line and curve diagrams. Defaults to ''50''. |
| dots | Size of circles to use to plot the given data points. Defaults to false (= not plotted). |
| shadow | Boolean value setting whether to draw shadows. Defaults to ''false''. |
| ticks | Boolean value setting whether to draw ticks on the axis of the diagram. Defaults to ''true''. |
| decimals | Decimals to display on axis labels and in pie chart percentages. Defaults to ''0''. |

==== Examples ====

=== Simple line chart ===

<charter>
title = Simple line chart
size = 700x230
align = center
bgcolor = #eeeeee
type = line
dots = 3
legendEntries = January, February

0,70,70,0,0,70,70,0,0,70
0.5,2,4.5,8,12.5,18,24.5,32,40.5,50
</charter>

<code>
<charter>
title = Simple line chart
size = 700x230
align = center
bgcolor = #eeeeee
type = line
dots = 3
legendEntries = January, February

0,70,70,0,0,70,70,0,0,70
0.5,2,4.5,8,12.5,18,24.5,32,40.5,50
</charter>
</code>

=== Simple bar chart ===

<charter>
title = Simple bar chart
size = 700x230
align = center
alpha = 90
bgcolor = #eeeeee
type = bar
legendEntries = January, February, March
thresholds = 0

1,4,-3,2,-3,3,2,1,0,7,4
3,3,-4,1,-2,2,1,0,-1,6,3
4,1,2,-1,-4,-2,3,2,1,2,2
</charter>

<code>
<charter>
title = Simple bar chart
size = 700x230
align = center
alpha = 90
bgcolor = #eeeeee
type = bar
legendEntries = January, February, March
thresholds = 0

1,4,-3,2,-3,3,2,1,0,7,4
3,3,-4,1,-2,2,1,0,-1,6,3
4,1,2,-1,-4,-2,3,2,1,2,2
</charter>
</code>

=== Simple 3D pie chart ===

<charter>
title = Simple 3D pie chart
size = 400x300
align = center
bgcolor = #eeeeee
type = pie3d
labelSerie = 2
pieExploded = on

10,2,3,5,3
Jan, Feb, Mar, Apr, May
</charter>

<code>
<charter>
title = Simple 3D pie chart
size = 400x300
align = center
bgcolor = #eeeeee
type = pie3d
labelSerie = 2
pieExploded = on

10,2,3,5,3
Jan, Feb, Mar, Apr, May
</charter>
</code>

=== Fancy cubic curve ===

<charter>
title = Fancy cubic curve
size = 700x230
align = center
type = cubicFilled
legendEntries = January, February
XAxisName = Items
YAxisName = Values
shadow = on
dots = 3
titleColor = #efefef
scaleColor = #efefef
shadowColor = #000
bggradient = #333@50
graphGradient = #666@50
fontLegend = VeraMono.ttf@8
graphLabels = 1|1|Point A, 2|3|Point B

100,320,200,50,63
50,432,79,153,234
</charter>

<code>
<charter>
title = Fancy cubic curve
size = 700x230
align = center
type = cubicFilled
legendEntries = January, February
XAxisName = Items
YAxisName = Values
shadow = on
dots = 3
titleColor = #efefef
scaleColor = #efefef
shadowColor = #000
bggradient = #333@50
graphGradient = #666@50
fontLegend = VeraMono.ttf@8
graphLabels = 1|1|Point A, 2|3|Point B

100,320,200,50,63
50,432,79,153,234
</charter>
</code>

===== Installation =====

==== With plugin manager ====

Let the manager do the dirty work, just give him this link to eat: {{plugin-charter.tar.gz}}

==== Without plugin manager ====

  - Download the plugin: {{plugin-charter.tar.gz}}
  - Extract it into your dokuwiki plugin folder (eg lib/plugins).

~~DISCUSSION~~