Difference: GaugePlugin ( vs. 1)

Revision 116 May 2013 - TWikiContributor

Line: 1 to 1
Added:
>
>

Gauge Plugin

<--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/GaugePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/GaugePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
Create gauges (graphical or not), typically used for dashboards

Introduction

This plugin can be used to build dashboards that contain graphical image gauges or non-graphical 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
simple This is identical to tambar with the exception that instead of creating a graphic it uses the HTML <table> tag to create the measure bar.
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 either an image representing the gauge or HTML <table> 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 = Create gauges (graphical or not), typically used for dashboards

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

  • Default gauge used. Possible values are: tambar, simple, or trend. Default: tambar
    • Set TYPE = tambar

  • Default way to access gauge data: inline or file.
    inline means the gauge image data is accessed via <img src="data:image/png;base64,<base64_data>" />
    file means the gauge image data is accessed from a created file.
    Caution should be used since depending on the age of browsers, there might be a max length limit to inline data or no support at all for inline images (i.e. IE7 and earlier don't support inline images). No limit is imposed in this plugin leaving this up to users to keep track of.
    • Set TAMBAR_ACCESS = file

  • 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
    • Set TAMBAR_SCALE_HEIGHT_PERCENTAGE = 20

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

Syntax Rules

The %GAUGE{...}% variable gets expanded to either an image representing the gauge or HTML <table> representing the gauge.

%GAUGE{}%
Parameters
Comment Default
type="tambar"
type="trend"
type="simple"
The type of gauge to be used, tambar for target measure bar (graphic), simple for target measure bar (non-graphic, only HTML), or trend for trend icon Global TYPE setting
name Name to uniquely identify the gauge file that is auto-created. None; required for tambar (not required for simple or trend)
value For tambar and simple: 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 (only used for tambar and trend) 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 and simple: 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 TAMBAR_SCALE setting
scalesize For tambar and simple: Defines the size, in percentage, of the scale size is relative to the height of the gauge. Values can be: scalesize="0" to scalesize="100" Global TAMBAR_SCALE_HEIGHT_PERCENTAGE setting
colors For tambar and simple: List of colors, each region has two colors. For trend: N/A Global TAMBAR_COLORS setting
access For tambar and simple define how the created image is accessed, Valid values are inline and file. Not support for trend

Caution should be used when using inline since some older browsers limit the max length of inline data or don't support inline images at all (i.e. IE7 and earlier don't support inline images). No limit is imposed in this plugin rather leaving it up to users to keep track of.
Global TAMBAR_ACCESS setting

<-- 
  • Set tambarTest1 = type="tambar" name="tambarTest1" scale="0, 10, 20, 40" value="27"
  • Set simpleTest1 = type="simple" name="simpleTest1" scale="0, 10, 20, 40" value="27"
  • Set trendTest1 = type="trend" name="trendTest1" value="-3"
-->

Examples

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

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

Output

  • For tambar and trend
    • access="file"
      • 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.
    • access="inline"
      • No image file is created, instead the image is sent inline in base64 format. %GAUGE{...}% gets expanded to an inline <img ... /> image tag like:
        • <img src="data:image/png;base64,<base64_data>" />
  • For simple
    • An HTML <table> is used to create the requested gauge. No file is created.

Error Handling

If the required parameters are not defined, then an error message is returned. If tambar, then the error might be returned in an <img ... /> image or as plan text. If simple, then the error will be returned inside of a <table%gt;.

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 TWiki server.

<--/twistyPlugin twikiMakeVisibleInline-->

  • 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/GaugePluginTests.txt Test page containing many examples of the GaugePlugin in action. Also shows various error conditions
    data/TWiki/VarGAUGE.txt Variable documentation topic
    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
  • Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.
  • Test if the plugin is correctly installed:
    • Check above examples if the "if installed" column shows images instead of variables.
    • Check GaugePluginTests for some more test

<--/twistyPlugin-->

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny, TWiki:Main.TaitCyrus
Copyright: © 2002-2013 TWiki:Main.PeterThoeny;
© 2008-2013 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2013-05-16
<--/twistyPlugin twikiMakeVisibleInline-->
2013-05-16: TWikibug:Item7154: Use TWISTY in installation instructions and change history
2012-11-13: TWikibug:Item7020: Categorize TWiki Variable -- TWiki:Main.PeterThoeny
2012-09-14: TWikibug:Item6933: Fix for generated img tag of tambar showing unsupported _RAW parameter -- TWiki:Main.PeterThoeny
2011-07-10: TWikibug:Item6725: Change global package variables from "use vars" to "our" -- TWiki:Main.PeterThoeny
2011-05-20:
  • TWikibug:Item6726 - Add new type="simple" which creates a gauge only using HTML <table> instead of creating a PNG image. This allows this plugin to be run without having to install the gd library
  • TWikibug:Item6728 - Add new option of access which defaults to file, but allows access="inline" to embed the image in HTML (no image needs to be created).
  • TWikibug:Item6729 - Fix bug with umask not getting reset after use.
-- TWiki:Main/TaitCyrus
2011-05-13:
  • TWikibug:Item6722 - Add ability to control scale height (from 0% to 100% of the gauge)
  • TWikibug:Item6723 - Fix data parsing issues that limited the use of very small values (like 0.01)
-- TWiki:Main/TaitCyrus
2010-05-06: TWikibug:Item6433 - Doc fixes -- TWiki:Main/PeterThoeny
2010-05-05: TWikibug:Item6419 - Validate and untaint input values -- TWiki:Main/PeterThoeny
2010-04-08: TWikibug:Item6420 - Added VarGAUGE variable documentation page; other doc improvements -- TWiki:Main/PeterThoeny
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)
<--/twistyPlugin-->
Dependencies: (optional) gd graphics library, http://www.libgd.org/
libpng PNG graphics library, http://www.libpng.org/pub/png/libpng.html
CPAN Dependencies (optional) CPAN:GD, CPAN:POSIX, CPAN:MIME::Base64
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: VarGAUGE, TWikiPreferences, TWikiPlugins

META FILEATTACHMENT attr="h" comment="Target Measure Bar, 60x16 example" date="1021945424" name="tambar1.gif" path="tambar1.gif" size="932" user="TWikiContributor" version="1.1"
META FILEATTACHMENT attr="h" comment="Trend Up Icon 16x16" date="1021945466" name="trendup.gif" path="trendup.gif" size="877" user="TWikiContributor" version="1.1"
META FILEATTACHMENT attr="h" comment="Trend Down Icon 16x16" date="1021945479" name="trenddn.gif" path="trenddn.gif" size="875" user="TWikiContributor" version="1.1"
META FILEATTACHMENT attr="h" comment="Trend Equal Icon 16x16" date="1021945497" name="trendeq.gif" path="trendeq.gif" size="869" user="TWikiContributor" version="1.1"
META FILEATTACHMENT attr="h" comment="Trend No Data Icon 16x16" date="1021945521" name="trendnd.gif" path="trendnd.gif" size="875" user="TWikiContributor" version="1.1"
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding RHUL Physics Department TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.GaugePlugin.