Dokuwiki Charter Plugin

I no longer actively maintain this plugin, it therefore is only provided “as is”.

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.

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 formatted¹⁾. 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:

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

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).

¹⁾ the charter plugin only understands very basic CSV, with the only accepted delimiter being a comma and no support for quoted values exists

Discussion

Nicholas Glykos, 2009/02/16 13:04

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

Peter Chao, 2009/02/27 16:14

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!!

Jonathan Alexander, 2009/04/26 22:41

Above fix didn't work for me (DokuWiki version: Release 2009-02-14). I had to change Peter's line above from:

require_once(DOKU_PLUGIN.'syntax.php'); //*** Peter

to:

require_once(DOKU_INC.'inc/plugin.php');

bobbelsche, 2009/03/13 14:43

Fatal error: Call to undefined function imagecreatetruecolor() in /usr/share/dokuwiki/lib/plugins/charter/lib/pchart/pChart.class.php on line 201

foosel, 2009/03/13 18:15

You don't have the gdlib module for PHP installed I'd say, which is needed by pchart.

Thomas, 2009/04/02 15:24

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

Thomas, 2009/04/02 15:37

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.

Thomas, 2009/04/02 15:53

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

Thomas, 2009/04/03 19:52

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

foosel, 2009/04/03 22:52

Great, thanks for debugging this issue, I'll add the info accordingly :-)

Thomas, 2009/04/28 16:28

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

nguyen, 2009/05/01 22:18

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

Experiments with Inside/Outside features and Cohesive Constraints

Besides, I want to start drawing from y=19, and I set threshold to 19 but It doesnt seems to work.

James, 2009/06/09 12:22

Hi all,

Thanks for this plugin very useful !

Do you think it is possible to add 2 functions ?

Set each element color
- Example in wiki code : “fgcolor = color1, color2, color3, …”
- Example in plugin config : color sequence : color1, color2, color3, …
Read ”<chart></chart>” code (same than wiki) directly from wiki media file (text file) and directly include it.

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 !

Cayle, 2009/07/10 10:58

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.

<charter>
title = Wiki access statistics
size = 700x230
align = center
bgcolor = #eeeeee
type = line
XAxisFormat=Date
legendEntries = Hits per day (x100), Visits per day,Month
labelSerie=3
2.59,4.56,8.83,7.82
19,32,44,36
Mar,Apr,May,Jun
</charter>

Arno Welzel, 2009/09/08 13:27

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.

Arno Welzel, 2009/09/11 07:21

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.

Josep Sanmarti, 2009/09/17 16:22

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.

2007	Gener	Febrer	Març	Abril	Maig	Juny	Juliol	Agost	Setembre	Octubre	Novembre	Decembre
Clickthroughts	10	12	15	10	18	7	20	15	9	6	10	12

Example data...

Arno Welzel, 2009/09/18 07:28

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

Josep Sanmarti, 2009/09/18 09:20

Thanks Arno, now it works perfect!

gljukonaft, 2009/10/19 20:24

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 !

Arno Welzel, 2009/10/19 22:40

I think, using non-latin symbols are impossible at the moment, since the chart library can not handle non-latin symbols with freetype fonts.

dosy07, 2010/01/05 23:06

Hi,

How to put date or hour in axis ?

cdt, dosy07

dosy07, 2010/01/07 14:50

Ok i found it with labelSerie

But how to put hour text with 90° because it is not readable in graph ?

Ralf, 2010/02/17 09:33

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.

Variation of bits_to_shift

Do you have any idea how to change this? Thanks in advance!

Ralf

Ralf, 2010/02/17 09:40

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

Thomas, 2010/04/08 18:07

I have this error:

Warning: Wrong parameter count for imageftbbox() in /export/db_mon/dokuwiki/lib/plugins/charter/lib/pchart/pChart.class.php on line 968

and many more of them. In the preview I see the graph after lot of these errors. But when I click save I see the same error messages but this one at the end:

Warning: Cannot modify header information - headers already sent by (output started at /export/db_mon/dokuwiki/lib/plugins/charter/lib/pchart/pChart.class.php:968) in /export/db_mon/dokuwiki/inc/common.php on line 1476

What went wrong?

E. Planas, 2010/11/10 14:00

Hi, Wonderful plugin : thank you indeed for making it available to the community.

Could you please help with this : In the graph below, the automatic calculus for the Yaxis tics divides the Yaxis into (0, 15, 30) . Is it possible to set the division by hand, say to (0, 2, 4, …, 28, 30) ?

Thank You.

Nb réponse par année

Django, 2011/03/09 09:16

How do you force an (automatic - every day| manual) update to the graph?

I want to update one graph, if datas has changed, but any changes I made are ignored. Only the first version of the chart is ever displayed. Specifying NOCACHE makes no difference either.

Any idea?

Robert Joy, 2011/03/13 16:55

Is there an auto-scale command for line graphs? I have a dataset that has high y-axis values (52000,52088,etc). I would like to have the y-axis focused around the data but I don't see a way to do that. Right now it starts at zero and goes to the max value in the set. In this mode I don't really see much of a change in the data because the y values never get remotely close to zero. Thanks for the help!

Nomek, 2013/02/04 16:34

Hello, It is possible to take over values like variables? I collect statistics over namespaces with wikistatistics like: wikistatistics>type=pages ns=en:doku

Now i want to use this value in a fancy graph like:

1,5,6,”wikistatistics>type=pages ns=en:doku”, 10, 12 etc. Is it possible to get dynamic stuff displayed which updates itself like others already ask?

Thanks, Regards, Normen

foosel, 2013/02/04 17:28

Nope, and that's not planned either.

You could leave a comment if you were logged in.

snippets/dokuwiki/charter.txt · Last modified: 2013/02/04 19:23 by foosel

Table of Contents

Table of Contents

Navigation

About me

Search

Quicklinks

RSS

Linkblog

Currently...

... playing

Toolbox

Dokuwiki Charter Plugin

Description

Dependencies

Acknowledgements

Updates

Syntax

Basic setup

Font settings

Color settings

Descriptional settings

Pie chart settings

Other settings

Examples

Simple line chart

Simple bar chart

Simple 3D pie chart

Fancy cubic curve

Installation

With plugin manager

Without plugin manager

Discussion

Table of Contents

Table of Contents

Navigation

About me

Search

Quicklinks

RSS

Blogroll

Linkblog

Currently...

... playing

Toolbox

Dokuwiki Charter Plugin

Description

Dependencies

Acknowledgements

Updates

Syntax

Basic setup

Font settings

Color settings

Descriptional settings

Pie chart settings

Other settings

Examples

Simple line chart

Simple bar chart

Simple 3D pie chart

Fancy cubic curve

Installation

With plugin manager

Without plugin manager

Discussion