cross is now running Foswiki 2.1.3 Beta 1. Please open a task for any issues. Happy Holidays!
TIP GaugePlugin is not installed on


Build dashboards that contain graphical images of gauges defined with %GAUGE% macros.


This plugin can be used to build dashboards that contain graphical images of gauges like tambar1.gif (target measure gauge) and trendup.gif (trend icons).

Two types of gauges are currently available, a target measure bar and a trend icon.

Type of Gauge Name What it Does Example
Target Measure Bar tambar Shows the actual state of a measure in a bar. The bar has two parts, the upper thick bar shows the actual value, the lower thin bar shows the scale of the gauge. For example regions with a relative distribution of bad (red), acceptable (yellow) and good (green) values Actual: 35
Trend Icon trend Shows the up trend, no change and down trend of a measure up trend, no change, down trend

The Target Measure Bar has scale regions (the lower thin bar) like red, yellow and green. Each region has a start and end boundary, the end boundary of one region is the start of the next. The scale determines the boundaries, e.g. a scale of 0, 10, 20, 40 has a red region with range 0...10, a yellow one with range 10...20 and a green one with range 20...40.

The upper value region (the thick bar) has two colors, a dark color used for actual value and a light color for filling out the rest of the gauge with a lighter color.

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

Plugin Settings

Plugin settings are stored as preferences values. You can override the defaults for these preferences in SitePreferences, the WebPreferences topic of the current web, or in individual topics that use the plugin. Changing them here will have no effect! This allows you to upgrade the plugin without having to worry about losing your settings.

  • Set DEBUG to 1 to get debug messages in the debug log file. Default: 0

  • Default gauge used: tambar, trend. Default: tambar
    • Set GAUGEPLUGIN_TYPE = tambar

  • Default dimensions, scale and colors for Target Measure Bar. See details in the syntax rules.
    • Set GAUGEPLUGIN_TAMBAR_SCALE = 0, 33, 67, 100

  • Default dimensions for Trend Icon

Syntax Rules

The %GAUGE{...}% variable gets expanded to an image representing the gauge.

%GAUGE% Parameter Comment Default
type The type of gauge to be used, tambar or trend Global TYPE setting
name Name to uniquely identify the gauge file that is auto-created. None; is required for tambar (not required for trend)
value For tambar: The actual value of the gauge
For trend: Positive = arrow up, 0 = arrow right, negative = arrow down
None. Show "no data" if missing
alt Alternate text for image Value is value parameter
width Defines the width of the gauge in pixels. Global <type>_WIDTH setting
height Defines the height of the gauge in pixels. Global <type>_HEIGHT setting
scale For tambar: Defines the number and position of the scales. For example a value of "5, 12, 35, 57" denotes that there are three regions on the bar gauge, "5...12", "12...35" and "35...57".
For trend: N/A
Global <type>_SCALE setting
colors For tambar: List of colors, each region has two colors. For trend: N/A Global <type>_COLORS setting


Type of gauge You type You should get... ...if installed
Target Measure Bar %GAUGE{ type="tambar" name="t1" scale="0, 10, 20, 40" value="27" }% 27 %GAUGE{ type="tambar" name="t1" scale="0, 10, 20, 40" value="27" }%
Trend Icon %GAUGE{ type="trend" name="t2" value="-3" }% down trend %GAUGE{ type="trend" name="t2" value="-3" }%

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

More examples can be found at GaugePluginTests.


  • A PNG graphics file is created containing the gauge results. The file is placed in %PUBURLPATH%/%WEB%/%TOPIC%/_GaugePlugin_<type>_<name>.png
  • %GAUGE{...}% 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.

Installation Instructions

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

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See for more help.

Check GaugePluginTests to verify the plugin is installed and working correctly.

Plugin Info

Plugin Author(s): Foswiki:Main.AndrewJones
Previous Author(s): TWiki:Main.PeterThoeny, TWiki:Main.TaitCyrus
Copyright: © 2009 - 2011, Andrew Jones, © 2002 - 2006, Peter Thoeny
License: GPL (Gnu General Public License)
Plugin Release: 1.2
Plugin Version: 11917 (2011-06-14)
Change History:  
14 Jun 2011: Foswiki:Tasks.Item10778: added extra params need by some versions of GD. Foswiki:Tasks.Item10879: Fixed bad parameters to image tag - Foswiki:Main.CrawfordCurrie
04 May 2011: Foswiki:Tasks.Item8544: Incorrect reference to WIKIPREFSTOPIC in documentation; Foswiki:Tasks.Item9928: fix umask; Foswiki:Tasks.Item8545: Links to GaugePluginTests; Code clean-up, using official API's - Foswiki:Main.AndrewJones
18 Mar 2009: Foswiki:Tasks.Item1254 - New 1.0 release for Foswiki - Foswiki:Main.AndrewJones
01 May 2003: Added time stamp to image to prevent browser from caching images; ignore non-numerical chars in value parameter; fixed warnings
08 Sep 2002: Added missing binmode (for Windows); pass parameters also to error image
23 May 2002: Initial version
16 May 2002: Initial spec
libgd>0Required. GD Library Available from
libpng>1.2.3Required. PNG Library. Available from

Related Topics: GaugePluginTests, DefaultPreferences, SitePreferences, Plugins

Topic revision: r7 - 14 Jun 2011, CrawfordCurrie - This page was cached on 25 Dec 2016 - 07:51.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License