Dokuwiki Charter Plugin
Description
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.
In case you come across any bugs in this plugin, please don't hesitate to report them.
The Git repository of the plugin can be found at Github.
Dependencies
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.
Acknowledgements
The charter plugin bundles the pChart library and the 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 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.
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:
pChart documentation
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>
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>
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
Thank you for making the charter plugin for dokuwiki. We love it. A quick question: is there a way to have the 'XAxisName' centered symmetrically about the middle point of the x axis ? (the way it is now, it is printed starting from the middle, and so, a long 'XAxisName' breaks the graphs' symmetry). If there is no standard way to do this, can you guide me where to start looking into your code ?
Thanks again, Nicholas
When preview, I got this error(dokuwiki 2009-02-14):
“Fatal error: Class 'DokuWiki_Plugin' not found in C:\DokuWikiStickNew\dokuwiki\lib\plugins\charter\helper.php on line 2”
After modify helper.php like this:
// must be run within Dokuwiki if (!defined('DOKU_INC')) die(); if (!defined('DOKU_LF')) define('DOKU_LF', "\n"); if (!defined('DOKU_TAB')) define('DOKU_TAB', "\t"); if (!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN', DOKU_INC.'lib/plugins/'); require_once(DOKU_PLUGIN.'syntax.php'); //*** Peter require_once(DOKU_PLUGIN.'charter/lib/pchart/pData.class.php'); require_once(DOKU_PLUGIN.'charter/lib/pchart/pChart.class.php'); class helper_plugin_charter extends DokuWiki_Syntax_Plugin {It's work!!
Above fix didn't work for me (DokuWiki version: Release 2009-02-14). I had to change Peter's line above from:
to:
Fatal error: Call to undefined function imagecreatetruecolor() in /usr/share/dokuwiki/lib/plugins/charter/lib/pchart/pChart.class.php on line 201
You don't have the gdlib module for PHP installed I'd say, which is needed by pchart.
Hello, I just installed this on Dokuwiki 2009-02-14 or whatever the latest version is.
However, when I preview a page or view a page where I saved it with a chart, I do not get any content at all. I get the header information for the page, but I get nothing after the content should be loading.
So I installed the plugin on a local install using the same version of both, and it worked fine.
GD is installed on both installs, although the test instance I set up doesn't have all of my additional plugins yet. I'm going to try adding them in to see if one is conflicting with another, but if any one else has run into this problem and can give me some guidance, that would be great.
Thanks
Nope, with all my plugins disabled it still would not work, so it isn't a conflict. I'll check the web server settings and see if I can enable more error logging.
It appears that I need to recompile GD to include freetype support. I caught on to this from this link: http://www.mail-archive.com/phpdoc@lists.php.net/msg36904.html
I'll do that and let you know how it works out.
Thoams
I downloaded and compiled Freetype, and then simply had to recompile php with the extra parameter –with-freetype-dir=/usr/local/lib to point the built in GD to the library. Once I restarted Apache, all was good. :)
Thomas
Great, thanks for debugging this issue, I'll add the info accordingly
Is there a way to include text labels for the x axis entries?
Actually, I answered this before I posted this, but since I've already gotten this written, I'll post it anyway since it might help someone else.
To do a text label on the x axis, set the labelSerie parameter to the number of the row that you have the labels written, and then include your text labels on the last line of your input. So:
….
labelSerie {equals symbol} 3
20,0,41
1,9,3
Already Transferred,Not Requested,Incorrectly Configured
Hi,
Thanks a lot for this wonderful plugin. Related to “text label on x-axis”, I follow your suggestions but have never got it works. Here is my snippet where I want to specify {nctest07} and {newstest08} to x-axis
Besides, I want to start drawing from y=19, and I set threshold to 19 but It doesnt seems to work.
Hi all,
Thanks for this plugin very useful !
Do you think it is possible to add 2 functions ?
Color settings will be better for esthetic, load from file is better for dynamic charts.
Thanks by advance, i try to do and if i success i send you the code !
How do you force an update to the graph?
I want to update my wiki access every month (see below), but any changes I make are ignored. Only the first version of the chart is ever displayed. Specifying NOCACHE makes no difference either.
How to handle multiple graphs with same title?
I have a wiki where the same graph title is used in a number of different pages, but all in the same namespace.
Unfortunately, this is not possible
- because all graphic files are named based on the graph title!
Example:
To document the progress in a project, where we use Scrum, we create one page for each sprint. And every page also has a burndown-chart with the obvious title “Burndown-Chart”.
So - the first graph created gets the file name “chart-burndown-chart.png”.
When creating another graph with the same title - but with different values of course - on another page, it *also* gets the name “chart-burndown-chart.png”.
So fix this, we use unique graph titles (“Burndown-Chart, Sprint #nn”). But it would be much easier, if charter would not just directly use the graph title for the filename. Maybe a checksum of the content would be better.
Ok - i realised, MD5 sum is used, if there is no title. I changed this code, so MD5 sum is always used. This will - of course - cause many files to be created, when editing the graph. On the other hand, this will lead to many different files, if the same graph gets changed often.
Maybe the plugin should not generate a static image, but store the graph contents and use a link to a helper to put out the image source, which automatically deletes old images (e.g. older than x days) and generates the graph image again.
I will see, what i can do there.
Oh - and another point: The default alignment “left” causes the image to float left. I added a new default “none” for myself, which means, the class used for the image is “media” and not “medialeft” or “mediarigh” - the default for images in DokuWiki.
Thank you for making the charter plugin for dokuwiki but I've a problem. I'm trying to plot some data per month during a whole year, so a 3D pie chart should have 12 pieces with 12 values and different colors and here is the problem. I just can have 8 different colors, the other 4 are black. Has anybody else experienced this? How can I solve it? Thanks! By the way, don't worry about some labels, is catalan language.
I'm not the creator of the plugin - but when you open lib/pchart/pChart.class.php you will find the following code
/* Palettes definition */ var $Palette = array("0"=>array("R"=>188,"G"=>224,"B"=>46), "1"=>array("R"=>224,"G"=>100,"B"=>46), "2"=>array("R"=>224,"G"=>214,"B"=>46), "3"=>array("R"=>46,"G"=>151,"B"=>224), "4"=>array("R"=>176,"G"=>46,"B"=>224), "5"=>array("R"=>224,"G"=>46,"B"=>117), "6"=>array("R"=>92,"G"=>224,"B"=>46), "7"=>array("R"=>224,"G"=>176,"B"=>46));This defines the 8 available colours. If you need more colors, just add them here with their RGB values, for example - one additional green (0, 255, 0) and red (255, 0, 0):
/* Palettes definition */ var $Palette = array("0"=>array("R"=>188,"G"=>224,"B"=>46), "1"=>array("R"=>224,"G"=>100,"B"=>46), "2"=>array("R"=>224,"G"=>214,"B"=>46), "3"=>array("R"=>46,"G"=>151,"B"=>224), "4"=>array("R"=>176,"G"=>46,"B"=>224), "5"=>array("R"=>224,"G"=>46,"B"=>117), "6"=>array("R"=>92,"G"=>224,"B"=>46), "7"=>array("R"=>224,"G"=>176,"B"=>46), "8"=>array("R"=>0,"G"=>255,"B"=>0), "9"=>array("R"=>255,"G"=>0,"B"=>0));"9"=>array("R"=>128,"G"=>224,"B"=>0),);</code>Hope this helps, Arno
Thanks Arno, now it works perfect!
Hi !
I install plugin and it is working.
But not display non-latin symbols: http://wiki.centercest.ru/dw/doku.php?id=playground:playground
As I can do it ?
Thanx !
I think, using non-latin symbols are impossible at the moment, since the chart library can not handle non-latin symbols with freetype fonts.
Hi,
How to put date or hour in axis ?
cdt, dosy07
Ok i found it with labelSerie
But how to put hour text with 90° because it is not readable in graph ?
Hi!
I installed the plugin and I really love it. Updating charts is so simple now, great work. But… Most of my data is between 0 and 1. If I render the following chart, I only see the values 0 and 1 (no decimals!) as labels on the y-axis, which is not very helpful.
Do you have any idea how to change this? Thanks in advance!
Ralf
So… When function drawScale is called the value of $Decimals is ”” (nothing). If $decimals is hard-coded to 2, it works:
/* Compute and draw the scale */ function drawScale($Data,$DataDescription,$ScaleMode,$R,$G,$B,$DrawTicks=TRUE,$Angle=0,$Decimals = 2,$WithMargin=FALSE,$SkipLabels=1,$RightScale=FALSE) { $Decimals = 2; // Change by Ralf