Chart Plugin (v1.401)

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.

ChartPlugin 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:

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

Error Handling

If the required parameters are not defined, then an error message is returned or an <img ... /> image tag is returned pointing to a graphic containing the error message.

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

• Download the ZIP file from the Plugin web (see below)
• Unzip ChartPlugin.zip in your TWiki installation directory. Content:

• If you see Permission denied errors, verify that ownership and permissions are correct for the following making sure that ownership and permissions match existing directories ownerships and permissions:
  • pub/TWiki/ChartPlugin
• Test if the plugin is correctly installed:
  • Check above examples if the "if installed" column shows images instead of variables.
  • Check ChartPluginTests for some more tests

Plugin Info

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.TaitCyrus - 3 June 2004
-- TWiki:Main.PeterThoeny - 16 Nov 2004