Feedback on GaugePlugin

This plugin was needed for my day-time job to build a dashboard application. Spec by Peter and Tait, programming done by TaitCyrus.

• This plugin is clean, e.g. it only uses published TWiki::Func::* functions.
• It generates images into the attachment directory of the topic, without any versioning. In order to avoid a nameclash with regular attachments we have these names: %PUBURLPATH%/%WEB%/%TOPIC%/_GaugePlugin_<type>_<name>.png or .gif
• The plugin generates GIF or PNG depending on the version of the GD library installed. PNG for GD lib version > 1.19, and GIF for older versions.

Possible Improvements:

• Other gauges like dials, regular bars, LEDs etc. Contributions are welcome!

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

-- PeterThoeny - 23 May 2002

Looks cool! When images/attachments are generated? On page save? Or each time page is viewed?

-- PeterMasiar - 24 May 2002

At page view time. This is spec because a GAUGE can be embedded in a SEARCH, that is, the gauge changes even if the topic does not. The IMG tags currently have a time-stamp parameter so that browsers do not cache the images. Performance is not too bad even with this simple setup.

A planned enhancement is to use hash value to create image files only when necessary, and to list this hash value in the URL so that the browser caches the image as long as it is the same.

-- PeterThoeny - 23 May 2002

I got this feedback at my workplace:

I'd like an option where I could get the gauge to show me the endpoints of the data range, and also to show the current value of the gauge.

something like this

         -------------------
       0 |             |   | 100
         -------------------
                      75

         -------------------
       0 |   |             | 100
         -------------------
            25

Would be useful for showing performance numbers and knowing the numerical scale.

I can see that this would be a useful option. Probably better to render the numbers into the graphic image (with some white space on the left and right side) so that the gauges align nicely when stacked on top of each other. This could be enabled with a new parameter switch.

-- PeterThoeny - 30 May 2002

I've tested it on Cygwin where it shows a small bug: the png/gif file must be opened in binary mode. Here is the needed patch:

--- GaugePlugin.pm.orig   2002-05-23 15:23:40.000000000 +0200
+++ GaugePlugin.pm   2002-08-16 10:30:59.000000000 +0200
@@ -249,6 +249,9 @@
     # Write image file.
     umask( 002 );
     open(IMAGE, ">$dir/$filename") || return _make_error "Can't create '$dir/$filename': $!";
+#AS
+    binmode IMAGE;
+#/AS
     if( $GD::VERSION > 1.19 ) {
    print IMAGE $im->png;
     } else {
@@ -457,6 +460,9 @@
     # Create the file.
     umask( 002 );
     open(IMAGE, ">$dir/$filename") || return _make_error "Can't create '$dir/$filename': $!";
+#AS
+    binmode IMAGE;
+#/AS
     if( $GD::VERSION > 1.19 ) {
    print IMAGE $im->png;
     } else {

-- AndreaSterbini - 16 Aug 2002

New version posted. Small fix for binmode (thanks Andrea); passing parameters also to the error image.

-- PeterThoeny - 08 Sep 2002

How about using an html table with coloured backgrounds as a poor man's gauge? The reason I set off this way is that I did not have GD on our server, and only wanted a really basic gauge display. So I did this (warning - newbie-level Perl ahead...):

# display gauge using html table
# pass in int value for percentange done
sub gaugeLite
{
    my $done = $_[0];
    my $todo = 100 - $done;
    my $line="<table border=1 width=100%><tr>\n";
    if ($done > 0) { $line .= "<td width=$done% bgcolor=\"#00ff00\">.</td>\n"; }
    if ($todo > 0) { $line .= "<td width=$todo% bgcolor=\"#ff0000\">.</td>\n"; }
    $line .= "</tr></table>\n";
    return $line;
}

which produces a display something like:

that can be embedded inside a field in a table. The dot in the <td> field is a hack to make the field display, which suggests this may not be a very robust solution, and it is certainly not elegant, but it seems to get the job done for really simple cases.

See Doc Graphics for another example MartyBacke - 15 Sep 2002

-- MartinWatt - 14 Sep 2002

Using a table with colored background is a simple and portable way to build bar charts, I used that at work once in a different context. (BTW, you could use a   instead of a dot.)

Yes, the tambar Gauge could have been done just with that. Initially I had plans to add other gauges like a round dial gauge to the GaugePlugin, there you would need a graphics library.

-- PeterThoeny - 15 Sep 2002

non-maintainer update synchronized cvs with released zip version, which was ahead of the cvs version

-- MattWilkie - 02 Apr 2004

Updated Plugin with benchmark numbers (no code changes)

-- PeterThoeny - 16 Nov 2004

Note to myself: The GaugePlugin docs could be a bit more explicit.

There are six colors, by default: dark red, light red, dark yellow, light yellow, dark green, and light green. The dark colors are used for the lower thin bar and for the left part of the upper thick bar (color depends on where the value is in relation to the lower bar). The right part of the upper thick bar uses the light color equivalent of the color in the left part.

-- PeterThoeny - 20 Oct 2005

I'm wondering if one could combine the GaugePlugin to make WebStatistics more transparent. Maybe there should be a HotSpotsPlugin that creates graphical representations of topics with much activity (read/write) like shown in the following two screenshots taken from GründerWiki resp. DorfWiki

-- FranzJosefSilli - 05 Nov 2005

This Plugin could be extended to SupportSparklines.

Example 1: %GAUGE{ type="sparkline" name="t1" value="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" }%

Produces:

Example 2: %GAUGE{ type="sparkbar" name="t2" value="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" }%

Produces:

The values would be scaled to fit in a default width="100" height="16", which can be changed. Also color="#880000" could be an additional parameter.

-- PeterThoeny - 28 Apr 2006