Chart Plugin

This plugin creates PNG or GIF charts to visualize TWiki tables using a default linear scale or an optional semilogarithmic scale.

Five types of charts, line, area, bar, scatter and combo, are currently available:

Type of Chart	Name	What it Does	Example
Area	area	Shows a chart using areas under a line to represent the data
Bar	bar	Shows a chart using bars to represent the data
Line	line	Shows a chart using simple lines, points only, or lines with points to represent the data. Note: Any areas that fall behind already drawn areas are drawn as lines to make them visible
Scatter	scatter	Shows a scatter chart (XY data points) and allows mixing area or bar with line, point, and pline
Combo	combo	Shows a chart combining the features from area or bar with line, point, and pline Note: Formally known as arealine which is still supported

The %CHART{...}% variable gets expanded to an image representing the chart. Parameters and global settings determine the type of chart, dimensions, and values.

HelpChart Global Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, for example, %CHARTPLUGIN_SHORTDESCRIPTION%

• One line description, shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Create PNG or GIF charts to visualize TWiki tables

• Set DEBUG to 1 to get debug messages in data/debug.txt. Default: 0
  • Set DEBUG = 0

• Default chart used: area, line, bar, scatter or combo. Default: line
  • Set TYPE = line

• Default dimensions, scale and colors for a chart. See details in the syntax rules.
  • Set WIDTH = 400
  • Set HEIGHT = 250
  • Set AREA_COLORS = #FF3333, #FFFF33, #33FF33, #CC66FF, #99FFFF, #FFCC00, #008000, #FF8080, #3366CC, #800080
  • Set LINE_COLORS = #FF0000, #FFCC00, #00CC00, #FF00FF, #33CCCC, #FF8000, #009900, #FF6666, #3333FF, #800080
  • Set BGCOLOR = #FFFFFF, #FFFFFF

• Define the grid color. When xgrid/ygrid = "on", then just use the first color when drawing grid lines. When their value is "dot", then use the full specification for drawing the grid lines ("transparent" can be used to introduce holes in the line).
  • Set GRIDCOLOR = #808080, #808080, #808080, transparent, transparent, transparent
  • Set NUMYGRIDS = 9

• Define what to do when an empty table cell is found. "none" means assume no default value. A value of "10" would mean empty cells would be assumed to have a value of 10
  • Set DEFAULTDATA = none

• Define the default scale: linear or semilog
  • Set SCALE = linear

• Define the number of pixels wide lines are drawn with
  • Set LINEWIDTH = 3

• Define the number of pixels (in both the X and Y directions) to use when drawing a point
  • Set POINTSIZE = 5

• Define bar chart specific parameters. BARSPACE defines the space (in pixels) between bars. BARLEADINGSPACE defines the leading space (in pixels) before the first bar. BARTRAILINGSPACE defines the trailing space (in pixels) after the last bar
  • Set BARLEADINGSPACE = 6
  • Set BARTRAILINGSPACE = 6
  • Set BARSPACE = 5

Syntax Rules

The %CHART{...}% variable gets expanded to an image representing the chart.

• Some parameters expect a range of table cells, using SpreadSheetPlugin syntax:
  • A table cell can be addressed as R1:C1. Cell addresses:

    R1:C1	R1:C2	R1:C3	R1:C4
    R2:C1	R2:C2	R2:C3	R2:C4

• A range of table cells is defined by two cell addresses separated by "..". For example, "row 1-20, column 3" is: R1:C3..R20:C3 and "row 15-5, column 2" is: R15:C2..R5:C2

Note: To support legacy syntax, datatype maps to subtype, arealine maps to combo.

Examples

Assuming the following three TWiki tables. The first shows the data oriented in columns while the seconds shows the data oriented in rows

Type of chart	You type	You should get...	...if installed
area	Multiple area %CHART{ type="area" name="area1" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%
bar	Multiple bars %CHART{ type="bar" name="bar1" table="exampleTable2" data="R3:C2..R5:C4" xaxis="R1:C2..R1:C4" legend="R3:C1..R5:C1" ymin="0" width="225" height="200" }%
line	Simple line %CHART{ type="line" name="line1" table="exampleTable1" data="R2:C2..R6:C2" xaxis="R2:C1..R6:C1" legend="R1:C2..R1:C2" width="225" height="200" }%
line	Multiple lines %CHART{ type="line" name="line2" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%
scatter	Multiple scatter %CHART{ type="scatter" subtype="pline" name="scatter1" table="exampleTable3" data="R2:C2..R6:C4" xaxis="R2:C1..R6:C1" legend="R1:C2..R1:C4" numxgrids="4" linewidth="1" width="225" height="200" }%
combo	Combo with area, pline, point, & line %CHART{ type="combo" subtype="area, pline, point, line" name="combo1" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%
combo	Combo with bar, pline, point, & line %CHART{ type="combo" subtype="bar, pline, point, line" name="combo2" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" }%

The "if installed" column shows images instead of variables in case the plugin is installed correctly.

Output

• A graphics file in PNG or GIF format is created containing the chart results. The file is placed in %PUBURLPATH%/%WEB%/%TOPIC%/_ChartPlugin_<type>_<name>.png or .gif (GIF for GD version 1.19 or older)
• %CHART{...}% gets expanded to an <img ... /> image tag.