ChartPlugin < TWiki < PlanetoWiki

TWiki Web>ChartPlugin (2014-11-04, TWikiAdminUser) (raw view)
---+!! Chart Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page
   at http://twiki.org/cgi-bin/view/Plugins/ChartPlugin or provide feedback
   at http://twiki.org/cgi-bin/view/Plugins/ChartPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>

This plugin helps you visualize data in TWiki tables as charts, using a default linear scale or an optional semi-logarithmic scale.

---++ Introduction

Six types of charts, _line_, _area_, _bar_, _scatter_, _combo_, and _spark_ 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 | <img alt="" src="%ATTACHURLPATH%/areaexample.png" /> |
| Bar | =bar= | Shows a chart using bars to represent the data | <img alt="" src="%ATTACHURLPATH%/barexample.png" /> |
| Line | =line= | Shows a chart using simple lines, points only, or lines with points to represent the data. %BR% __Note:__ Any areas that fall behind already drawn areas are drawn as lines to make them visible | <img alt="" src="%ATTACHURLPATH%/lineexample.png" /> |
| Scatter | =scatter= | Shows a scatter chart (XY data points) and allows mixing =area= or =bar= with =line=, =point=, and =pline= | <img alt="" src="%ATTACHURLPATH%/scatterexample.png" /> |
| Combo | =combo= | Shows a chart combining the features from =area= or =bar= with =line=, =point=, and =pline= %BR% __Note:__ Formally known as =arealine= which is still supported | <img alt="" src="%ATTACHURLPATH%/comboexample.png" /> |
| Sparkline | =sparkline= | Shows a [[http://en.wikipedia.org/wiki/Sparkline][sparkline]]. Sparklines are small graphs <span style="vertical-align:text-bottom"><img alt="" src="%ATTACHURLPATH%/sparklineexample.png" style="vertical-align:text-bottom" /></span> that are part of the flow of a sentence or paragraph. ||
| Sparkbar | =sparkbar= | Shows a <span style="vertical-align:text-bottom"><img alt="" src="%ATTACHURLPATH%/sparkbarexample2.png" /></span> sparkline in the shape of small bars. ||
| Sparkarea | =sparkarea= | Shows a <span style="vertical-align:text-bottom"><img alt="" src="%ATTACHURLPATH%/sparkareaexample.png" /></span> sparkline in the shape of an area. ||

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

---++ <nop>%TOPIC% Global Settings

Plugin settings are stored as preferences variables. Do not change the settings here, overload them in [[%LOCALSITEPREFS%]]. To overload a plugin setting, prefix it with =CHARTPLUGIN_=. For example, to overload the =BGCOLOR= setting, add a =* Set CHARTPLUGIN_BGCOLOR = ...= bullet in <nop>%LOCALSITEPREFS%.

   * Short description: 
      * Set SHORTDESCRIPTION = Visualize TWiki tables with area charts, bar charts, line graphs, scatter charts and sparklines

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

   * Set CACHE to 1 to enable caching of topic data.  So if you have 1 topic page with numerous charts, the topic page will only be parsed once for table data for all charts instead of once for each chart.
      * Set CACHE = 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
   * Define the default background colors.  The first color is the area outside of the chart, the second color is the area inside the chart, and the third color is the color inside of data label boxes.
      * Set BGCOLOR = #FFFFFF, #FFFFFF, #FFFFFF

   * Define the number of grids and 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).  By default, the system will auto calculate the number of Y grids to draw (up to a max of 9).  Specify a value for =NUMYGRIDS= for a system wide absolute defautl setting.
      * Set GRIDCOLOR = #808080, #808080, #808080, transparent, transparent, transparent
      * Set NUMYGRIDS = 
   * Define the chart border color.  Can be 'transparent';
      * Set BORDERCOLOR = #000000

   * 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

   * The following bar parameters are now obsolete and are no longer used. They are replaced with the new bar parameters shown below.
      * Set BARLEADINGSPACE = 6
      * Set BARTRAILINGSPACE = 6
      * Set BARSPACE = 5
   * New bar chart specific parameters.  The following values are all relative to each other and define the relative sizes of various bar widths.  =BARLEADINGSPACEUNITS= defines how wide the space is before the first bar. =BARTRAILINGSPACEUNITS= defines how wide the space is after the last bar. =BARSPACEUNITS= defines how wide the space is between bars. =BARWIDTHUNITS= defines how wide the actual bars are.
      * Set BARLEADINGSPACEUNITS = 1
      * Set BARWIDTHUNITS = 2
      * Set BARSPACEUNITS = 1
      * Set BARTRAILINGSPACEUNITS = 1
   * The following parameters are specific to =sparkbar= and are all relative to each other and define the relative sizes of various spark bar widths. =SPARKBARSPACEUNITS= defines how wide the space is between spark bars and =SPARKBARWIDTHUNITS= defines how wide the actual spark bars are.
      * Set SPARKBARWIDTHUNITS = 2
      * Set SPARKBARSPACEUNITS = 1

   * Define the default error generation behavior.  Are any errors shown as simple =text=, inside of an =image=, or no error at all with =none=
      * Set SHOWERROR = text

---++ Syntax Rules

The =%<nop>CHART{...}%= variable gets expanded to an image representing the chart.

   * Some parameters expect a range of table cells, using *extended* SpreadSheetPlugin syntax: 
      * A single table cell can be addressed as ==R1:C1== where cell addresses are:
         | ==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==
   * Ranges can be discontinuous. Discontinous ranges are joined using =="+"== or ==","==. For example: ==R4:C1..R5:C2+R9:C1..R15:C2==.
   * When you are specifying datasets, you specify the range so that you have one data set per row (column). You can also specify multiple data sets using discontinuous blocks of cells; for example, ==R4:C1..R5:C2,R9:C1..R10:C2== specifies *4* data sets: R4:C1..R4:C2, R5:C1..R5:C2, R9:C1..R9:C2 and R10:C1..R10:C2
   * It is possible to specify a constant value instead of a range of table cells.  For example: ==R1:C3..R20:C3,0== as a =data= or =data2= value would create a data set with the constant value = =0= which could be used to highlight the zero line when data is both negative and positive, or ==R1:C1..R1:C3,0== as a =datalegend= value would set the legend of the 4th data set = =0=.
   * ==+== has higher precedence than ==,==
   * All parameters ending with =2= (like: =data2= and =ylabel2=) are relative to the right Y axis.  The default is relative to the left Y axis.

| *%<nop>CHART% Parameter* | *Comment* | *Default* |
| =type= | The type of chart to create. One of ="area"=, ="bar"=, ="line"=, ="scatter"=, ="combo"=, ="sparkline"=, ="sparkbar"=, or ="sparkarea"= | Global =TYPE= setting |
| =subtype= and =subtype2= | Sub type of selected data. =subtype= applies to =data= while =subtype2= applies to =data2=.  Supported values depend on chart type: | |
| ^ | - for =type="area"=: =&nbsp;&nbsp;&nbsp;&nbsp;subtype="area"= | ="area"= |
| ^ | - for =type="bar"=: =&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;subtype="bar"= | ="bar"= |
| ^ | - for =type="line"=: =&nbsp;&nbsp;&nbsp;&nbsp;subtype="line, point, pline"= (point line) | ="line"= |
| ^ | - for =type="scatter"=: =&nbsp;subtype="area, bar, line, point, pline"= %BR%Note: you cannot mix =area= and =bar= on the same chart.%BR%Note: It is not recommended using showing a =bar= on a =scatter= chart as the X axis placement is skewed with =bar= and will not exactly line up with drawn X axis values which will defeat the purpose of using =scatter= in the first place. | ="point"= |
| ^ | - for =type="combo"=: =&nbsp;&nbsp;&nbsp;subtype="area, bar, line, point, pline"= (note: you can not mix =area= and =bar= on the same chart) | 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 |
| =table= | TWiki table used to build the chart. A numerical value refers to the table number, where "1" is the first table seen in a topic. Any other non-numeric string refers to a named table defined by the =TABLE= variable with a =name= parameter. For example, table="trends" refers to the table that is preceded by =%<nop>TABLE{ name="trends" }%=. | ="1"= |
| =title= | The title placed at the top of the chart | None |
| =xlabel= | The label placed under the X axis describing the X values | None |
| =ylabel= and =ylabel2= | The label placed to the left of the left Y axis (=ylabel=) or right of the right Y axis (=ylabel2=) describing the Y values | None |
| =data= and =data2= | The source data displayed on the chart. Values specified with =data= are displayed relative to the left Y axis while values specified with =data2= are displayed relative to the right Y axis. In both cases, they define either a range of table cells or explicit data values. For example for =type="line"=, a =data="R2:C3..R999:C6"= would say that four lines were to be drawn with the first line being rows 2-999 column 3 and last line being rows 2-999 column 6. In the case of a scatter graph, data represents the actual Y values. Note: Reversed data is allowed so =data="R999:C6..R2:C3"= is a legal data specification. Explicit data is also allowed so =data="R999:C6..R2:C3,0"= would draw 5 lines, the first 4 coming from the table and the 5th having a constant value of =0=. | None; is required for all charts |
| =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= and =yaxis2= | Y-Axis labels for the left Y axis and the right Y axis: ="on"= to show the labels, ="off"= for no labels. | ="off"= |
| =xmin= | Minimum value drawn on the X axis. Note: this is *only* applicable for =scatter= charts. | The minimum value specified by =xaxis= |
| =xmax= | Maximum value drawn on the X axis. Note: this is *only* applicable for =scatter= charts. | The maximum value specified by =xaxis= |
| =ymin= and =ymin2= | Minimum value drawn on the left (=ymin=) and right (=ymin2=) Y axis | The minimum value specified by =data= and =data2= |
| =ymax= and =ymax2= | Maximum value drawn on the left (=ymax=) and right (=ymax2=) Y axis | The maximum value specified by =data= and =data2= |
| =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 Y axis grids drawn | Global =NUMYGRIDS= setting |
| =ytics= and =ytics2= | Number of tic marks to draw between Y axis grid lines for the left (=ytics=) and right (=ytics2=) Y axis.  | 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= and =datalabel2= | Shows data value labels above drawn data points for =data= and =data2= data.  Possible values are: <table border="0" cellspacing="0" cellpadding="0"><tr><td valign="top"> ="off"= </td><td> Do not show any data value labels </td></tr><tr><td valign="top"> ="on"= </td><td> Show the data value labels for all data points </td></tr><tr><td valign="top"> ="box"= </td><td> Show the data value labels inside of a box for all data points </td></tr><tr><td> ="auto"= </td><td> Show the data value labels for only data points falling on an X-axis grid line.  This option should be used when there are a lot of data points and the data values start to be drawn on top of each other making them impossible to read.</td></tr><tr><td valign="top"> <div style="white-space: nowrap"> ="autobox"= or%BR% ="auto box"= or%BR% ="boxauto"= or%BR% ="box auto"= </div> </td><td> Show the data value labels inside of a box for only data points falling on an X-axis grid line.  This option should be used when there are a lot of data points and the data values start to be drawn on top of each other making them impossible to read. </td></tr><tr><td valign="top"> ="##"= %BR% (an integer number) </td><td> Show the first and last data value labels along with trying to show (=##= - 2) additional data value labels in between. An even distribution of data value labels will be shown so it is possible that fewer data value labels than requested will be displayed.  For example with 16 data values charted, requesting ="7"=, ="8"=, or ="9"= data value labels would only show a total of 8. </td></tr><tr><td valign="top"> <div style="white-space: nowrap"> ="##box"= or%BR% ="## box"= or%BR% ="box##"= or%BR% ="box ##"= </div> </td><td> Show the first and last data value labels inside of a box along with trying to show (=##= - 2) additional data value labels (in boxes) in between. An even distribution of data value labels will be shown so it is possible that fewer data value labels than requested will be displayed.  For example with 16 data values charted, requesting ="7"=, ="8"=, or ="9"= data value labels would only show a total of 8. </td></tr></table> | ="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.%BR%Note: if =type="sparkbar"= and =width="0"=, then the width will be auto computed to be the minimum width to allow easily readable spark bars. | Global =WIDTH= setting |
| =height= | Defines the overall height of the chart in pixels. | Global =HEIGHT= setting |
| =alt= | Alternate text for chart image | Empty alt tag |
| =colors= and =colors2= | A list of colors defining the color of each set of data points for =data= and =data2=. Color values are of the form: Hexadecimal RGB color ="#ffffff"= or ="transparent"= | Global =LINE_COLORS= setting for lines; global =AREA_COLORS= setting for area |
| =bgcolor= | Background color of the area surrounding/outside the chart, the area inside the chart, and the data label boxes.  Color values are of the form: Hexadecimal RGB color ="#ffffff"= or ="transparent"=.  For example, ="#e7e7e7"= sets a light gray background (outside the chart) color.  Optionally specify a second values for the chart background itself (the inside color) and an optional third value which is the value of the color to fill data label boxes with. For example, ="#e7e7e7, #ffffc0"= defines a chart with a light yellow inside background on a light gray outside, with default data label box background color. | Global =BGCOLOR= setting |
| =gridcolor= | Colors/style of the grid (if any). If =xgrid="on"= or =ygrid="on"= then use the first =gridcolor= for drawing solid grid lines. If =xgrid="dot"= or =ygrid="dot"=, then use the full set of colors to define the line style for drawing the grid lines. ="transparent"= can be used to introduce holes in the line." | Global =GRIDCOLOR= setting |
| =linewidth= | Width of data lines in pixel | Global =LINEWIDTH= setting |
| =pointsize= | Size of data points in pixel | Global =POINTSIZE= setting |
| =showerror= | Specify how any error messages are handled.  Possible values are:%BR%<ul><li> ="text"= -- all error messages are produced as regular (red) text</li><li> ="image"= -- all error message are placed inside of an image sized according to the size of the chart if there were no error.</li><li> ="none"= or ="no"= -- no error messages are produced.  HTML text of =&<nop>nbsp;= is returned</li></ul> | Global =SHOWERROR= setting |
| =errmsg_nodata= and =errmsg_nodata2= | =errmsg_nodata=: Specify a custom error message when no data is available.  =errmsg_nodata2=: Specify a custom error message when no data in =data2= is available.%BR%These are useful when this plugin is charting data from %<nop>DBI_QUERY% and no data is returned from this query and you want your own custom error message instead of the generic plugin error message. | Default plugin error message. |
| (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 three TWiki tables. The first shows the data oriented in columns while the seconds shows the data oriented in rows
<table>
<tr>
<td valign="top">
*Table 1*
%TABLE{name="exampleTable1"}%
| *Year* | *Actual* |
| 1998   | 9 |
| 1999   | 14 |
| 2000   | 19 |
| 2001   | 25 |
| 2002   | 39 |
</td>
<td>
&nbsp;
</td>
<td valign="top">
*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 |
</td>
<td>
&nbsp;
</td>
<td valign="top">
*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 | 2 | 3 | 8 |
</td>
</tr>
</table>

<!-- To make things a bit easier to read, we define TWiki variables to
    contain the sample charts.
   * Set area1 = name="area1" table="exampleTable2" type="area" data="R2:C2..R99:C6" xaxis="R1:C2..R1:C99" legend="R2:C1..R99:C1" ymax="30" width="225" height="200" numygrid="4"
   * Set bar1 = name="bar1" table="exampleTable2" type="bar" data="R3:C2..R99:C4" xaxis="R1:C2..R1:C4" legend="R3:C1..R99:C1" ymin="0" ymax="19" numygrids="9" width="225" height="200"
   * Set line1 = name="line1" table="exampleTable1" type="line" data="R2:C2..R6:C2" xaxis="R2:C1..R6:C1" legend="R1:C2..R1:C2" ymin="5" ymax="40" numygrids="6" width="225" height="200"
   * Set line2 = name="line2" table="exampleTable2" type="line" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" ymin="5" ymax="30" numygrids="4" width="225" height="200"
   * Set scatter1 = name="scatter1" table="exampleTable3" type="scatter" subtype="pline" data="R2:C2..R6:C4" xaxis="R2:C1..R6:C1" legend="R1:C2..R1:C4" ymin="1" ymax="10" xmax="12" numygrids="8" numxgrids="8" linewidth="1" width="225" height="200"
   * Set combo1 = name="combo1" table="exampleTable2" type="combo" subtype="area, pline, point, line" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" ymin="5" ymax="30" numygrids="4" numxgrids="4" width="225" height="200"
   * Set combo2 = name="combo2" table="exampleTable2" type="combo" subtype="bar, pline, point, line" data="R2:C2..R5:C6" xaxis="R1:C2..R1:C6" legend="R2:C1..R5:C1" ymin="5" ymax="30" numygrids="4" numxgrids="4" width="225" height="200"
   * Set sparkline = name="sparkline" type="sparkline" data="88, 84, 82, 92, 82, 86, 66, 82, 44, 64, 66, 88, 96, 80, 24, 26, 14, 0, 0, 26, 8, 6, 6, 24, 52, 66, 36, 6, 10, 14, 30" width="75" height="16" colors='#224262' bgcolor='transparent'
   * Set sparkbar1 = name="sparkbar1" type="sparkbar" data="88, 84, 82, 92, 82, 86, 66, 82, 44, 64, 66, 88, 96, 80, 24, 26, 14, 0, 0, 26, 8, 6, 6, 24, 52, 66, 36, 6, 10, 14, 30" width="75" height="16" colors='#224262' bgcolor='transparent'
   * Set sparkbar2 = name="sparkbar2" type="sparkbar" data="88, 84, 82, 92, 82, 86, 66, 82, 44, 64, 66, 88, 96, 80, 24, 26, 14, 0, 0, 26, 8, 6, 6, 24, 52, 66, 36, 6, 10, 14, 30" width="0" height="16" colors='#224262' bgcolor='transparent'
   * Set sparkarea = name="sparkarea" type="sparkarea" data="88, 84, 82, 92, 82, 86, 66, 82, 44, 64, 66, 88, 96, 80, 24, 26, 14, 0, 0, 26, 8, 6, 6, 24, 52, 66, 36, 6, 10, 14, 30" width="75" height="16" colors='#224262' bgcolor='transparent'
-->

| *Type of chart* | *You type* | *You should get...* | *...if installed* |
| area | Multiple areas %BR%%BR% =%<nop>CHART{%area1%}%= | <img alt="" src="%ATTACHURLPATH%/area1.png" /> | %CHART{%area1%}% |
| bar | Multiple bars %BR%%BR% =%<nop>CHART{%bar1%}%= | <img alt="" src="%ATTACHURLPATH%/bar1.png" /> | %CHART{%bar1%}% |
| line | Simple line %BR%%BR% =%<nop>CHART{%line1%}%= | <img alt="" src="%ATTACHURLPATH%/line1.png" /> | %CHART{%line1%}% |
| line | Multiple lines %BR%%BR% =%<nop>CHART{%line2%}%= | <img alt="" src="%ATTACHURLPATH%/line2.png" /> | %CHART{%line2%}% |
| scatter | Multiple scatter %BR%%BR% =%<nop>CHART{%scatter1%}%= | <img alt="" src="%ATTACHURLPATH%/scatter1.png" /> | %CHART{%scatter1%}% |
| combo | Combo with area, pline, point, & line %BR%%BR% =%<nop>CHART{%combo1%}%= | <img alt="" src="%ATTACHURLPATH%/combo1.png" /> | %CHART{%combo1%}% |
| combo | Combo with bar, pline, point, & line %BR%%BR% =%<nop>CHART{%combo2%}%= | <img alt="" src="%ATTACHURLPATH%/combo2.png" /> | %CHART{%combo2%}% |
| sparkline | sparkline %BR%%BR% =%<nop>CHART{%sparkline%}%= | %BR%<img alt="" src="%ATTACHURLPATH%/sparklineexample.png" /> | %BR%%CHART{%sparkline%}% |
| sparkbar | sparkbar %BR%%BR% =%<nop>CHART{%sparkbar1%}%= | %BR%<img alt="" src="%ATTACHURLPATH%/sparkbarexample1.png" /> | %BR%%CHART{%sparkbar1%}% |
| sparkbar | sparkbar (=width="0"= so the width will be auto sized) %BR%%BR% =%<nop>CHART{%sparkbar2%}%= | %BR%<img alt="" src="%ATTACHURLPATH%/sparkbarexample2.png" /> | %BR%%CHART{%sparkbar2%}% |
| sparkarea | sparkarea %BR%%BR% =%<nop>CHART{%sparkarea%}%= | %BR%<img alt="" src="%ATTACHURLPATH%/sparkareaexample.png" /> | %BR%%CHART{%sparkarea%}% |

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

---++ Charts with SEARCH and CALC

Charts can be created dynamically based on TWiki tables with SEARCH and CALC.

[[%SYSTEMWEB%.VarSEARCH][SEARCH]]: Create a table dynamically with a [[%SYSTEMWEB%.FormattedSearch][formatted search]], then visualize it with a CHART. If the number of rows in a table is not known, specify a big row number in the CHART, such as =data="R2:C2..R999:C7"=. The !ChartPlugin is smart enough to use the actual number of rows.

[[%SYSTEMWEB%.VarCALC][CALC]]: Table cells can be created dynamically with SpreadSheetPlugin formulas. Here is an example table that sums up the total in the right hand column:
<table>
<tr>
<td valign="top">
*Raw text of table:* <verbatim>
%TABLE{name="exampleTableWithCALC"}%
|   | A | B | Total |
| 1 | 7 | 9 | %CALC{$SUM(R$ROW():C1..R$ROW():C3)}% |
| 2 | 5 | 2 | %CALC{$SUM(R$ROW():C1..R$ROW():C3)}% |
| 3 | 5 | 7 | %CALC{$SUM(R$ROW():C1..R$ROW():C3)}% |
</verbatim>
</td>
<td>
&nbsp;
</td>
<td valign="top">
*Table:* 
%TABLE{name="exampleTableWithCALC"}%
|   | A | B | Total |
| 1 | 7 | 9 | %CALC{$SUM(R$ROW():C1..R$ROW():C3)}% |
| 2 | 5 | 2 | %CALC{$SUM(R$ROW():C1..R$ROW():C3)}% |
| 3 | 5 | 7 | %CALC{$SUM(R$ROW():C1..R$ROW():C3)}% |
</td>
<td>
&nbsp;
</td>
<td valign="top">
*Resulting chart:* %BR% 
%CHART{ type="line" table="exampleTableWithCALC" name="line3" data="R2:C2..R4:C7" legend="R1:C2..R1:C7" xaxis="R2:C1..R4:C1" yaxis="on" datalabel="on" ymin="0" ymax="20" width="250" height="140" }%
</td>
</tr>
</table>

__%X% Attention:__ You can get unexpected results if you [[%SYSTEMWEB%.VarINCLUDE][INCLUDE]] a topic that has a CHART pointing to a table with CALCs. By default, the SpreadSheetPlugin delays CALCs in included topics and evaluates them once all INCLUDEs are processed. With that, the CHART in an included topic sees unprocessed CALCs, resulting in a chart with incorrect values. To get he desired result you need to set the following preference setting in the topic that _includes_ the topic containing the CHART:

   * Set SPREADSHEETPLUGIN_SKIPINCLUDE = 0

This setting tells the !SpreadSheetPlugin to process the CALCs in the included page, e.g. it will not delay the evaluation of the formulas.

---++ Output

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

---++ Error Handling

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

---++ Plugin Installation Instructions

%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

__Note:__ You do not need to install anything on the browser to use this extension. The following instructions are for the administrator who installs the extension on the TWiki server.

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the extension home on twiki.org (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory.
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies (if any).

   * Plugin __configuration and testing__: 
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional plugin settings in the __Extensions__ section if needed.
      * Test if the installation was successful using the examples provided.

   * Check above examples if the "if installed" column shows images instead of variables.
   * Check ChartPluginTests for some more tests
%ENDTWISTY%

---++ Plugin Info

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny, TWiki:Main.TaitCyrus |
|  Copyright: | &copy; 2002-2013 Peter Thoeny, [[http://twiki.org/][TWiki.org]]  <br /> &copy; 2008-2013 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2013-05-23 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}%"
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2013-05-23: | TWikibug:Item7265: ChartPlugin: generating PNG is not optional. |
|  2013-05-16: | TWikibug:Item7154: Use TWISTY in installation instructions and change history |
|  2012-12-10: | TWikibug:Item7069: ChartPlugin doesn't support multiple disks |
|  2012-11-11: | TWikibug:Item7020: Categorize TWiki Variable CHART |
|  2012-09-20: | TWikibug:Item6939: Use existing image file after "makeChart" subroutine fails to write. |
|  2012-09-08: | TWikibug:Item6837: Doc fixes |
|  2011-09-12: | TWikibug:Item6800: Fix for using qw(...) as parentheses, which is deprecated in Perl 5.14 -- TWiki:Main.PeterThoeny |
|  2011-08-23: | TWikibug:Item6791: Added new ChartPlugin default setting CACHE that allows users to either allow topic page caching or not -- TWiki:Main.TaitCyrus |
|  2011-08-02: | TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny |
|  2011-06-02: | <ul><li> TWikibug:Item6740: Add new parameters =errmsg_nodata= and =errmsg_nodata2= providing the ability to specify a custom error message when there is no data to chart.</li><li> TWikibug:Item6742: Fixed =spark= data handing all inline data and no data from a table</li></ul> -- TWiki:Main.TaitCyrus |
|  2011-06-01: | TWikibug:Item6741: Minor doc fix -- TWiki:Main.EnriqueCadalso |
|  2011-05-27: | TWikibug:Item6735: Fix bug with constant data -- TWiki:Main.TaitCyrus |
|  2011-05-13: | TWikibug:Item6701: Doc improvements; use transparent background for sparkline examples -- TWiki:Main.PeterThoeny |
|  2011-05-13: | <ul><li> TWikibug:Item6720: Allow support for =transparent= to be used in =colors= and =bgcolor= </li></ul> -- TWiki:Main.TaitCyrus |
|  2011-05-11: | <ul><li> TWikibug:Item6716: Add ability to support constant values in addtion to spreadsheet ranges.</li><li> TWikibug:Item6717: Fix bug with =area= colors when =data2= is used.</li><li> TWikibug:Item6718: Add new types: =sparkline=, =sparkbar=, and =sparkarea= </li><li> TWikibug:Item6719: Retool how bar widths/spaces are used/calculated so they are now proportional instead of fixed sizing</li></ul> -- TWiki:Main.TaitCyrus |
|  2011-05-05: | TWikibug:Item6714: Enhance error processing by adding =showerror= option.%BR%-- TWiki:Main.TaitCyrus |
|  2011-05-03: | <ul><li>TWikibug:Item6709: Fix runtime warnings.</li><li> TWikibug:Item6705: Remove dependency on TWiki:Plugins.SetGetPlugin</li><li> TWikibug:Item6706: Add support for both a left and right Y-axis (plus new tests).</li><li> TWikibug:Item6707: Add ability to change the =datalabel= background color (plus new tests).</li><li> TWikibug:Item6703: Added greater control over number of =datalabels= drawn (plus new tests).</li><li> TWikibug:Item6708: Remove custom plugin parameter parser instead using TWiki::Attrs.</li></ul> -- TWiki:Main.TaitCyrus |
|  2011-04-27: | <ul><li> TWikibug:Item6702: Fix positioning of x-axis labels when bar graph and xaxisangle=90</li><li> TWikibug:Item6703: Enhanced =datalabel= to allow =auto= and =autobox= values/li></ul> -- TWiki:Main.TaitCyrus |
|  2011-04-26: | Fixed bugs:<ul><li> TWikibug:Item6691: Fixed missing reverse tables</li><li> TWikibug:Item6691: Fixed =semilog= bug where data values didn't match yaxis values.</li><li> TWikibug:Item6692: Fixed bug where data containing HTML or TWiki links was not parsed correctly</li><li> TWikibug:Item6693: Fixed bug where if all data was identical, an error was generated about there being no height to the chart.  Now in this case, the =ymax= will be forced to the next higher value so the data will be drawn.</li><li> TWikibug:Item6694: Fixed bug with handling of =numxgrids= parameter.</li></ul>Enhancements:<ul><li> TWikibug:Item6695: improved reversed data charting</li><li> TWikibug:Item6695: Added improved support for reversed data ranges so bottom/up or right/left data can now be specified.</li><li> TWikibug:Item6696: Improved default values for X/Y axis min/max to be moved up (for max) or down (for min) nearest 1*, 2*, 5* range</li><li> TWikibug:Item6697: Added =xmin= and =xmax= for greater =scatter= chart specificaion.</li><li> TWikibug:Item6698: Allow single quote ='= in parameters in addition to ="=.</li><li> TWikibug:Item6699: Added caching of table processing in a topic so multiple charts on the same topic page will only parse the topic page once instead of each time a chart was created.</li><li>Updated the tests topic to be more human readable in raw mode by using %<NOP>SET{}% and %<NOP>GET{}%.</li><li>Added new tests to ChartPluginTests.</li></ul> -- TWiki:Main.TaitCyrus |
|  2010-11-04: | TWikibug:Item6600: Better doc of data parameter in the case of a scatter graph -- TWiki:Main.VickiBrown |
|  2010-06-26: | TWikibug:Item6003: Document CHARTs with SEARCHes and CALC in an INCLUDEd topic |
|  2010-04-07: | TWikibug:Item6160: Fixed taint issue with certain combination of Perl/GD; TWikibug:Item6329 - input validation for chart width and height; added VarCHART variable documentation page -- TWiki:Main.PeterThoeny |
|  2009-10-23: | TWikibug:Item6355: Fixed bug where chart not drawn if table at end of topic; Item6329: Added input validation for all parameters expected to be integers or real numbers - TWiki:Main.PeterThoeny |
|  18 May 2007: | Added discontinuous ranges - TWiki:Main.CrawfordCurrie |
|  16 Nov 2004: | V1.401 - Added benchmarks (no code changes) |
|  30 Aug 2004: | V1.400 - Added support for =subtype="bar"= (includes various global bar settings), updated =gridcolor= to not only define the grid color but allowing the user to define the line style (for drawing user defined dotted lines), add a global for how wide lines are drawn instead of a hard coded value, change the order of how things are drawn so now the order is: areas, grid lines and X/Y axis labels, bars, lines/points/plines, rectangle around chart, data point labels, chart title/X/Y labels, and finally the legends. |
|  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 =&lt;u&gt;25%&lt;/u&gt;= |
|  20 Jun 2002: | Initial version (V1.000) |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki dependencies: | $TWiki::Plugins::VERSION 1.1 |
|  Dependencies: | gd (see http://www.libgd.org/) |
|  CPAN Dependencies | CPAN:GD, CPAN:POSIX, CPAN:Text::Wrap |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle 96%, %SYSTEMWEB%.FormattedSearch 97%, ChartPlugin 69% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ VarCHART, ChartPluginTests, ChartPluginTestsRemote, %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
png	area1.png	r1	manage	1.7 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	area3.png	r1	manage	1.6 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	areaexample.png	r1	manage	3.3 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	arealine4.png	r1	manage	1.7 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	arealineexample.png	r1	manage	4.1 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	bar1.png	r1	manage	1.0 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	barexample.png	r1	manage	1.8 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	combo1.png	r1	manage	1.7 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	combo2.png	r1	manage	1.5 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	comboexample.png	r1	manage	3.0 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	line1.png	r1	manage	1.2 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	line2.png	r1	manage	1.9 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	lineexample.png	r1	manage	2.4 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	scatter1.png	r1	manage	2.0 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	scatterexample.png	r1	manage	1.8 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	sparkareaexample.png	r1	manage	0.2 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	sparkbarexample1.png	r1	manage	0.2 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	sparkbarexample2.png	r1	manage	0.2 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
png	sparklineexample.png	r1	manage	0.2 K	2013-05-23 - 13:11	TWikiAdminUser	Saved by install script
Topic revision: r2 - 2014-11-04 - TWikiAdminUser
TWiki
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding PlanetoWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.ChartPlugin.