Dokuwiki Charter Plugin
The Dokuwiki Charter Plugin provides a syntax for drawing highly customizable charts using the pChart library. Currently line, curve, bar and pie graphs are supported.
The Git repository of the plugin can be found at Github.
In order for the pChart library and therefore the charter plugin to work, you need to have GDlib support (with Freetype compiled in) enabled in your PHP installation.
Last updated: 2008/12/21
- Initial release
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 formatted1). Example:
<charter> param1 = value param2 = value 1, 2, 3, 4, 5 2, 3, 4, 5, 1 3, 4, 5, 1, 2 </charter>
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 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.
These are the only settings you should set on any graph you generate.
|title||The title of the graph to be displayed. Defaults to an empty string.|
|size|| The size of the generated graph. Format is
|align|| Alignment of the generated graph image. Can be either of
|type|| Type of the graph to generate. Supported types are
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.
|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.|
All color settings except the gradients must be formatted as HTML RGB specification, e.g.
#RGB. The leading
# is optional.
|bgcolor|| Background color of the whole graph. Defaults to
|legendColor|| Background color of legend box. Defaults to
|graphColor|| Background color of the graph area. Defaults to
|titleColor|| Foreground color of the title. Defaults to
|scaleColor|| Foreground color of the scale. Defaults to
|shadowColor|| Color of the drop shadow. Defaults to
|bggradient|| Gradient definition of the gradient to use as background for the whole chart. Format ist
|graphGradient|| Gradient definition of the gradient to use as background for the graph area. Format ist
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
|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
|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
|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
Documentation for axis formats:
- 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
Pie chart settings
Special settings only applying to pie charts. Boolean values can be
1 for true and
0 for false.
|pieLabels|| Boolean value setting whether to show labels in the pie chart. Defaults to
|piePercentages|| Boolean value setting whether to show percentages in the pie chart. Defaults to
|pieExploded|| Boolean value setting whether to draw the pie chart in exploded state. Defaults to
When drawing pie charts, there must be only one data serie, or two if one of them is declared as
Boolean values can be
1 for true and
0 for false.
|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
|legend|| Boolean value setting whether to show the legend. Defaults to
|grid|| Boolean value setting whether to draw the grid. Defaults to
|alpha|| Alpha value to use for drawing grid, bar charts and filled line and curve diagrams. Defaults to
|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
|ticks|| Boolean value setting whether to draw ticks on the axis of the diagram. Defaults to
|decimals|| Decimals to display on axis labels and in pie chart percentages. Defaults to
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>
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>
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>
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>
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).