Skip to topic | Skip to bottom
Home
TWiki
TWiki.GaugePluginr1.7 - 02 May 2003 - 06:08 - PeterThoenytopic end

Start of topic | Skip to actions

Gauge Plugin

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.

GaugePlugin Global Settings

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

  • One line description, shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Build dashboards that contain graphical images of gauges defined with %GAUGE{}% variables.

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

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

  • Default dimensions, scale and colors for Target Measure Bar. See details in the syntax rules.
    • Set TAMBAR_WIDTH = 60
    • Set TAMBAR_HEIGHT = 16
    • Set TAMBAR_SCALE = 0, 33, 67, 100
    • Set TAMBAR_COLORS = #FF0000, #FFCCCC, #FFFF00, #FFFFCC, #00FF00, #CCFFCC

  • Default dimensions for Trend Icon
    • Set TREND_WIDTH = 16
    • Set TREND_HEIGHT = 16

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

Examples

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 GaugePlugin error: Can't create '/home/groups/i/ib/ibo/htdocs/twiki/TWiki/GaugePlugin/_GaugePlugin_tambar_t1.png': 13
Trend Icon %GAUGE{ type="trend" name="t2" value="-3" }% down trend -3

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

Output

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

Plugin Installation Instructions

Note: You do not need to install anything on your 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 GaugePlugin.zip in your twiki installation directory. Content: | File: | Description: | | lib/TWiki/Plugins/GaugePlugin.pm | Plugin Perl module | | data/TWiki/GaugePlugin.txt | Plugin topic | | data/TWiki/GaugePlugin.txt,v | Plugin topic repository | | data/TWiki/GaugePluginTests.txt | Test page containing many examples of the GaugePlugin in action. Also shows various error conditions | | data/TWiki/GaugePluginTests.txt,v | RCS file for above | | pub/TWiki/GaugePlugin/tambar1.gif | Sample tambar image | | pub/TWiki/GaugePlugin/trenddn.gif | trend down arrow | | pub/TWiki/GaugePlugin/trendeq.gif | trend no change arrow | | pub/TWiki/GaugePlugin/trendup.gif | trend up arrow | | pub/TWiki/GaugePlugin/trendnd.gif | trend error message if value is not specified |
  • Test if the plugin is correctly installed:
    • Check above examples if the "if installed" column shows images instead of variables.
    • Check Gauge Plugin Tests for some more test

Plugin Info

Plugin Author: PeterThoeny, TWiki:Main/TaitCyrus
Plugin Version: 01 May 2003
Change History:  
01 May 2003: Added time stamp to image to prevent browser from caching images; ignore non-numerical chars in value parameter; fixed warnings (V1.002)
08 Sep 2002: Added missing binmode (for Windows); pass parameters also to error image (V1.001)
23 May 2002: Initial version (V1.0)
16 May 2002: Initial spec (V1.0)
CPAN Dependencies: GD from http://stein.cshl.org/WWW/software/GD
Other Dependencies: gd library from http://www.boutell.com/gd (Tested with 1.8.4)
PNG graphics library from http://www.libpng.org/pub/png
Perl Version: 5.005
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/GaugePlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/GaugePluginDev

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main/TaitCyrus - 23 May 2002
-- PeterThoeny - 01 May 2003
to top


You are here: TWiki > GaugePlugin

to top

Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback