| |
Gauge Plugin
This plugin creates PNG graphic files displaying gauge information, useful to build dashboards.
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 think bar shows the actual value, the lower thin bar shows regions with a relative distribution of bad (red), acceptable (yellow) and good (green) values |
 |
| Trend Icon |
trend |
Shows the up trend, no change and down trend of a measure |
 ,  ,  |
The Target Measure Bar has regions 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. Each region has two colors, a dark color used for actual values, 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.
GaugePlugin1 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 = Creates PNG graphic files displaying gauge information, useful to build dashboards.
- Set DEBUG to 1 to get debug messages in
data/debug.txt. Default: 0
- Default gauge used:
tambar, trend. Default: 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, 10, 20, 30
- Set TAMBAR_COLORS = #FF0000, #800000, #FFFF00, #FFFFCC, #00FF00, #008000
- 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 either in gauge creation (creating and storing the graphics making up the gauge) or gauge referencing (accessing an already created gauge graphics) |
None; is required |
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 of 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="1, 10, 20, 40" value="35" }% |
|
%GAUGE{ type="tambar" name="t1" scale="1, 10, 20, 40" value="35" }% |
| Trend Icon |
%GAUGE{ type="trend" name="t2" value="-3" }% |
|
%GAUGE{ type="trend" name="t2" value="-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.
Planned Improvements
- Hash value to enhance performance:
- Build hash value (checksum) of each gauge based on initial settings and attributes, and store hash value.
- Regenerate image only of hash value is different.
- Since there are so few gauge attributes you could use the actual gauge string (expanded with initial values) as the hash value
- Idea for hash value file name:
_GaugePlugin_<type>_<name>.hash, alternatively generate one hash value file per TWiki topic.
- Create a AttachmentStorePlugin that does the attachment storage handling; offers an API for plugins to use.
Plugin Installation Instructions
- Download the ZIP file from the Plugin web (see below)
- Unzip
GaugePlugin1.zip in your twiki installation directory. Content: | File: | Description: | data/TWiki/GaugePlugin1.txt | Plugin topic | data/TWiki/GaugePlugin1.txt,v | Plugin topic repository | lib/TWiki/Plugins/GaugePlugin1.pm | Plugin Perl module |
- Test if the plugin is correctly installed:
- Check above examples if the "if installed" column shows images instead of variables.
Plugin Info
Related Topics: TWikiPreferences, TWikiPlugins
-- PeterThoeny - 14 May 2002 |
