|
<
< |
Chart Plugin
|
>
> |
Chart Plugin (v1.300)
|
|
|
|
<
< |
This plugin creates PNG or GIF charts to visualize TWiki tables.
|
>
> |
This plugin creates PNG or GIF charts to visualize TWiki tables using a default linear scale or an optional semilogarithmic scale.
|
|
|
|
<
< |
Three types of charts are currently available, an area chart that shows data as areas under a line, a line chart that shows data as simple lines, and arealine which combines area and line.
|
>
> |
Four types of charts are currently available, an area chart that shows data as areas under a line, a line chart that shows data as simple lines, a scatter chart that shows XY data points (allows mixing area, line, point, and pline), and a combo chart (formally known as arealine and still supported) which allows mixing area, line _point_, and pline.
|
|
All data is specified via TWiki tables.
| Type of Chart | Name | What it Does | Example |
|---|
| Area | area | Shows a chart using areas under a line to represent the data |  |
| Line | line | Shows a chart using simple lines to represent the data. All data points on one of the lines are shown with their values |  |
|
|
<
< |
| Area and Line combined | arealine | Shows a chart combining the features from area and line. |  |
|
>
> |
| Scatter | scatter | Shows a scatter chart combining the features from area, point, and pline. All data points on the points are shown with their values |  |
| Area, Line, Point and Pline combined | combo | Shows a chart combining the features from area, point, and pline. |  |
|
|
The %CHART{...}% variable gets expanded to an image representing the chart. Parameters and global settings determine the type of chart, dimensions, and values.
|
|
a plugin setting write %<plugin>_<setting>%, for example, %CHARTPLUGIN_SHORTDESCRIPTION%
|
|
<
< |
-
- Set SHORTDESCRIPTION = Create PNG or GIF charts to visualize TWiki tables.
|
>
> |
-
- 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
|
|
<
< |
- Default chart used:
area, line, or arealine. Default: line
|
>
> |
- Default chart used:
area, line, scatter or combo. Default: 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
|
|
<
< |
-
- Set AREA_COLORS = #FF3333, #FFFF33, #33FF33, #CC66FF, #33CCFF, #FFCC00, #996633, #33CCCC, #3366CC
- Set LINE_COLORS = #0000FF, #00FF00, #FF0000, #FF6600, #FF00FF, #0099FF, #000000
|
>
> |
-
- Set GRIDCOLOR = #808080
- Set NUMYGRIDS = 9
- Set DEFAULTDATA = none
- Set SCALE = linear
- Set POINTSIZE = 5
|
|
Syntax Rules
|
|
-
- 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
|
>
> |
- 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
|
|
| %CHART% Parameter | Comment | Default |
|---|
|
|
<
< |
type | The type of chart to create, area, line, or arealine | Global TYPE setting |
|
>
> |
type | The type of chart to create. One of "area", "line", "scatter", "combo" | Global TYPE setting |
subtype | Sub type of chart. Supported values depend on chart type: | |
| ^ | - for type="line" chart: subtype="line, point, pline" (point line) | "line" |
| ^ | - for type="area" chart: subtype="area" | "area" |
| ^ | - for type="scatter" chart: subtype="area, line, point, pline" | "point" |
| ^ | - for type="combo" chart: subtype="area, line, point, pline" | All but the last data set are drawn as "area" and the last is drawn as "line" |
| ^ | You can use a comma delimited list of values to set a specific subtype for each data set. For example "area, area, point, line" would say that the first two data sets are areas, the third is point and the last one is a line | |
scale | The scale to use when creating the chart. "linear" or "semilog" | Global SCALE setting |
|
|
name | Name to uniquely identify the chart file that is auto-created. | None; is required for all charts |
web | The web in which to find topic (specified below) in which to find the TWiki tables | The current web |
topic | The topic in which to find the TWiki tables | The current topic |
|
|
xlabel | The label placed under the X axis describing the X values | None |
ylabel | The label placed to the left of the Y axis describing the Y values | None |
data | The source data to build the chart, defined as a range of table cells. For example for type="line", a data="R2:C3..R999:C6" would say that four lines were to be drawn with first line being rows 2-999 column 3 and last line being rows 2-999 column 6. | None; is required for all charts |
|
|
<
< |
datatype | For type="arealine" only: An "area, line" list defining how to represent the data. For example "area, area, area, line" would say that the first three data sets are areas and the last one is a line. | All but the last data set are assumed to be area and the last data set is assumed to be line |
xaxis | X-Axis labels: The values are defined as a range of table cells. The range also defines the orientation -- row or column oriented (if specified). For example "R2:C2..R999:C2" would take all of column 2 starting at row 2 and going through row 999. It would also denote that all remaining data is oriented columnar. | None. If not specified, then no X axis labels shown and data assumed to be in columnar format. |
|
>
> |
defaultdata | If there is sparse data, then use the value specified by defaultdata to fill in the missing data. A value of "none" means only draw actual data points. | Global DEFAULTDATA setting |
xaxis | X-Axis labels: The values are defined as a range of table cells. In case of scatter graph, xaxis represents the actual X values. The range also defines the orientation -- row or column oriented (if specified). For example "R2:C2..R999:C2" would take all of column 2 starting at row 2 and going through row 999. It would also denote that all remaining data is oriented columnar. | None. Is required for type="scatter". If not specified, then no X axis labels shown and data assumed to be in columnar format. |
xaxisangle | Angle the X-Axis labels are drawn. Only two angles are supported at this time, "0" draws horizontal labels, other numbers draw vertical labels | "0" |
|
|
yaxis | Y-Axis labels: "on" to show the labels, "off" for no labels. | "off" |
|
|
<
< |
ymin | Minimum value drawn on the Y axis. Nice human readable values are calculated from the data values if ymin and ymax are unspecified. | The minimum value specified by data |
|
>
> |
ymin | Minimum value drawn on the Y axis | The minimum value specified by data |
|
|
ymax | Maximum value drawn on the Y axis | The maximum value specified by data |
xgrid | Grid shown for X axis: "on" for solid grid lines, "dot" for dotted grid lines, "off" for none. | "dot" |
ygrid | Grid shown for Y axis: "on" for solid grid lines, "dot" for dotted grid lines, "off" for none. | "dot" |
|
|
<
< |
numygrids | Number of grids drawn for Y axis. This value gets adjusted up or down if ymin and ymax are unspecified so that the grid values fall on nice human readable values | Global NUMYGRIDS setting |
|
>
> |
numygrids | Number of Y axis grids drawn | Global NUMYGRIDS setting |
ytics | Number of tic marks to draw between Y axis grid lines. | If scale="semilog", then ytics="10", else defaults to "0" |
numxgrids | Number of X axis grids drawn. This can be used if there are a large number of X axis data points such that the X axis labels overlap. | Draw all X-Axis labels |
|
|
datalabel | Show data labels: "on" for labels, "box" for label in a box, "off" for none. It can also be a list like "off, off, off, box" to show values in a box for the fourth set of data points only. | "off" |
legend | Legend shown to the right of the chart. For example "R1:C3..R1:C6" would take all of row 1 starting at column 3 and going through column 6 as the name/legend of each set of data points | None; no legend if not specified |
width | Defines the overall width of the chart in pixels. | Global WIDTH setting |
height | Defines the overall height of the chart in pixels. | Global HEIGHT setting |
|
|
<
< |
alt | Alternate text for image | Empty alt tag |
|
>
> |
alt | Alternate text for chart image | Empty alt tag |
|
|
colors | A list of colors defining the color of each set of data points. | Global LINE_COLORS setting for lines; global AREA_COLORS setting for area |
bgcolor | Background color of the area surrounding the chart. For example, "#E7E7E7" sets a light gray background. Optionally specify a second values for the chart background itself. For example, "#E7E7E7, #FFFFC0" defines a chart with a light yellow background on a light gray surrounding. | Global BGCOLOR setting |
|
|
>
> |
gridcolor | Color of the grid (if any) | Global GRIDCOLOR setting |
|
|
| (other parameters) | Other parameters are passed on to the img tag. Useful to add additional image parameters like align="right" | None |
|
|
>
> |
Note: To support legacy syntax, datatype maps to subtype, arealine maps to combo.
|
|
Examples
|
|
<
< |
Assuming the following two TWiki tables. The first shows the data oriented in columns while the seconds shows the data oriented in rows
|
>
> |
Assuming the following three TWiki tables. The first shows the data oriented in columns while the seconds shows the data oriented in rows
|
|
|
|
>
> |
|
Table 1:
%TABLE{name="exampleTable1"}% |
|
|
| Year | Actual |
|---|
| 1998 | 9 |
| 1999 | 14 |
|
|
|
|
>
> |
| |
Table 2:
%TABLE{name="exampleTable2"}%
|
|
|
| Year | 1998 | 1999 | 2000 | 2001 | 2002 |
|---|
| Low | 8 | 10 | 13 | 17 | 22 |
|---|
| Target | 10 | 12 | 17 | 20 | 25 |
|---|
| High | 12 | 15 | 19 | 24 | 29 |
|---|
| Actual | 9 | 14 | 15 | 19 | 27 |
|---|
|
|
>
> |
| |
Table 3:
%TABLE{name="exampleTable3"}%
| X | Y1 | Y2 | Y3 |
|---|
| 3 | 1 | 3 | 7 |
| 6 | 5 | 8 | 10 |
| 11 | 3 | 5 | 9 |
| 10 | 1 | 3 | 7 |
| 8 | 1 | 2 | 8 |
|
|
|
| Type of chart | You type | You should get... | ...if installed |
|---|
|
|
<
< |
| line | %CHART{ type="line" name="t1" table="4" data="R2:C2..R6:C2" xaxis="R2:C1..R6:C1" yaxis="on" legend="R1:C2..R1:C2" width="225" height="200"}% |  | ChartPlugin error: Required Perl module 'GD' not found |
| line | %CHART{ type="line" name="t2" table="5" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" yaxis="on" legend="R2:C1..R5:C1" width="225" height="200"}% |  | ChartPlugin error: Required Perl module 'GD' not found |
| area | %CHART{ type="area" name="t3" table="5" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" yaxis="on" legend="R2:C1..R5:C1" width="225" height="200"}% |  | ChartPlugin error: Required Perl module 'GD' not found |
| arealine | %CHART{ type="arealine" name="t4" table="5" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" yaxis="on" legend="R2:C1..R5:C1" datatype="area area area line" width="225" height="200"}% |  | ChartPlugin error: Required Perl module 'GD' not found |
|
>
> |
| 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"}% | | ChartPlugin error: Required Perl module 'GD' not found |
| line | %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"}% | | ChartPlugin error: Required Perl module 'GD' not found |
| scatter | %CHART{ type="scatter" name="scatter1" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" width="225" height="200" numxgrids="4"}% |  | ChartPlugin error: Required Perl module 'GD' not found |
| 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"}% | | ChartPlugin error: Required Perl module 'GD' not found |
| combo | %CHART{ type="combo" name="combo1" table="exampleTable2" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" datatype="area pline point line" width="225" height="200"}% |  | ChartPlugin error: Required Perl module 'GD' not found |
|
|
The "if installed" column shows images instead of variables in case the plugin is installed correctly.
|
|
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.
|
>
> |
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:
|
>
> |
- Unzip
ChartPlugin.zip in your TWiki installation directory. Content:
|
|
| File: | Description: |
|---|
data/TWiki/ChartPlugin.txt | Plugin topic |
|
|
<
< |
data/TWiki/ChartPlugin.txt,v | Plugin topic repository |
|
|
data/TWiki/ChartPluginTests.txt | Test page containing many examples of the ChartPlugin in action. Also shows various error conditions |
|
|
<
< |
data/TWiki/ChartPluginTests.txt,v | RCS file for above |
|
|
data/TWiki/ChartPluginTestsRemote.txt | Topic containing remote tables referenced by ChartPluginTests |
|
|
<
< |
data/TWiki/ChartPluginTestsRemote.txt,v | RCS file for above |
|
|
pub/TWiki/ChartPlugin/line1.png | Sample line image |
pub/TWiki/ChartPlugin/line2.png | Sample line image |
pub/TWiki/ChartPlugin/area3.png | Sample area image |
|
|
<
< |
pub/TWiki/ChartPlugin/arealine4.png | Sample arealine image |
|
>
> |
pub/TWiki/ChartPlugin/scatter1.png | Sample scatter image |
pub/TWiki/ChartPlugin/combo1.png | Sample combo image |
|
|
pub/TWiki/ChartPlugin/lineexample.png | Sample line image |
pub/TWiki/ChartPlugin/areaexample.png | Sample area image |
|
|
<
< |
pub/TWiki/ChartPlugin/arealineexample.png | Sample arealine image |
|
>
> |
pub/TWiki/ChartPlugin/scatterexample.png | Sample scatter image |
pub/TWiki/ChartPlugin/comboexample.png | Sample combo image |
|
|
lib/TWiki/Plugins/ChartPlugin.pm | Plugin Perl module |
lib/TWiki/Plugins/ChartPlugin/Chart.pm | Chart library Plugin Perl module |
lib/TWiki/Plugins/ChartPlugin/Table.pm | Table library Plugin Perl module |
|
|
Plugin Info
|
|
<
< |
|
>
> |
|
|
| Change History: | <!-- specify latest version first --> |
|
|
<
< |
| 10 Oct 2002: | V1.003 - Improved performance, fixed bugs with color allocation, auto-legend placement and parsing of numbers in tables. Also bumped the upper value when numbers switch from decimal format to engineering format |
| 30 Sep 2002: | V1.002 - Add support for better placement of legends so they don't overlap, add auto ymin/ymax determination if not specified, add bgcolor and numygrids options |
|
>
> |
| 13 May 2004: | V1.300 - Added support for type="scatter"; renamed type="arealine" to "combo" (arealine is undocumented); renamed datatype to subtype (datatype is undocumented); added subtype options "point" and "pline", added new settings GRIDCOLOR, DEFAULTDATA, POINTSIZE; fixed bug with how the number of grids were drawn |
| 17 Oct 2003: | V1.201 - Fix boundary cases with semilog scale |
| 16 Oct 2003: | V1.200 - Add new options of scale and ytics. |
| 16 Jun 2003: | V1.100 - Add support for reversed tables (R999..R1), add new options of xaxisangle, numxgrids, and defaultdata, and allow sparse data. |
| 7 Oct 2002: | V1.003 - Improved performance, fixed bugs with color allocation, auto-legend placement and parsing of numbers in tables. Also bumped the upper value when numbers switch from decimal format to engineering format |
| 13 Sept 2002: | V1.002 - Add support for better placement of legends so they don't overlap, add auto ymin/ymax determination if not specified, add bgcolor and numygrids options |
|
|
| 27 Jun 2002: | V1.001 - Data range specified is clipped to actual table size; more forgiving data parsing by extracting first numeral from a table cell, e.g. extract 25 from <u>25%</u> |
| 20 Jun 2002: | Initial version (V1.000) |
| CPAN Dependencies: | GD from http://stein.cshl.org/WWW/software/GD |
|
|
Related Topics: TWikiPreferences, TWikiPlugins
|
|
<
< |
-- TaitCyrus? - 10 Oct 2002
-- PeterThoeny - 10 Oct 2002
| META FILEATTACHMENT | line1.png | attr="h" comment="" date="1034358856" path="C:\Data\MyTWiki\Plugins\ChartPlugin\pub\TWiki\ChartPlugin\line1.png" size="1247" user="PeterThoeny" version="1.2" |
|---|
| META FILEATTACHMENT | line2.png | attr="h" comment="" date="1034358866" path="C:\Data\MyTWiki\Plugins\ChartPlugin\pub\TWiki\ChartPlugin\line2.png" size="2289" user="PeterThoeny" version="1.2" |
|---|
| META FILEATTACHMENT | lineexample.png | attr="h" comment="" date="1024533198" path="C:\Data\MyTWiki\Plugins\ChartPlugin\pub\TWiki\ChartPlugin\lineexample.png" size="2462" user="PeterThoeny" version="1.1" |
|---|
| META FILEATTACHMENT | area3.png | attr="h" comment="" date="1034358879" path="C:\Data\MyTWiki\Plugins\ChartPlugin\pub\TWiki\ChartPlugin\area3.png" size="1988" user="PeterThoeny" version="1.2" |
|---|
|
>
> |
-- TWiki:Main.TaitCyrus - 13 May 2004
-- TWiki:Main.PeterThoeny - 14 May 2004
| META FILEATTACHMENT | line1.png | attr="h" comment="" date="1084562520" path="line1.png" size="987" user="PeterThoeny" version="1.3" |
|---|
| META FILEATTACHMENT | line2.png | attr="h" comment="" date="1084562531" path="line2.png" size="2023" user="PeterThoeny" version="1.3" |
|---|
| META FILEATTACHMENT | lineexample.png | attr="h" comment="" date="1084562541" path="lineexample.png" size="2462" user="PeterThoeny" version="1.1" |
|---|
| META FILEATTACHMENT | area3.png | attr="h" comment="" date="1084562463" path="area3.png" size="1813" user="PeterThoeny" version="1.3" |
|---|
|
|
| META FILEATTACHMENT | areaexample.png | attr="h" comment="" date="1024533210" path="C:\Data\MyTWiki\Plugins\ChartPlugin\pub\TWiki\ChartPlugin\areaexample.png" size="3370" user="PeterThoeny" version="1.1" |
|---|
| META FILEATTACHMENT | arealine4.png | attr="h" comment="" date="1034358891" path="C:\Data\MyTWiki\Plugins\ChartPlugin\pub\TWiki\ChartPlugin\arealine4.png" size="2102" user="PeterThoeny" version="1.2" |
|---|
| META FILEATTACHMENT | arealineexample.png | attr="h" comment="" date="1024533223" path="C:\Data\MyTWiki\Plugins\ChartPlugin\pub\TWiki\ChartPlugin\arealineexample.png" size="4211" user="PeterThoeny" version="1.1" |
|---|
|
|
>
> |
| META FILEATTACHMENT | combo1.png | attr="h" comment="" date="1084562500" path="combo1.png" size="1712" user="PeterThoeny" version="1.1" |
|---|
| META FILEATTACHMENT | comboexample.png | attr="h" comment="" date="1084582643" path="comboexample.png" size="3071" user="PeterThoeny" version="1.2" |
|---|
| META FILEATTACHMENT | scatter1.png | attr="h" comment="" date="1084562555" path="scatter1.png" size="1000" user="PeterThoeny" version="1.1" |
|---|
| META FILEATTACHMENT | scatterexample.png | attr="h" comment="" date="1084562564" path="scatterexample.png" size="3231" user="PeterThoeny" version="1.1" |
|---|
|
