W2H: Using Extra Buttons and Extra Items

Table of Contents

Introduction
Extra Buttons in Advanced Mode
Extra Buttons in Simple Mode
Extra Items in Advanced Mode
The Quota Bar example

Introduction

The Extra Buttons and Extra Items feature in W2H easily allows you to extend the button panel in the Main Window with buttons/images/applets executing site specific functions. In W2H's Simple Mode the "Extras" appear in their own window after clicking on a special Extra-Tab.

Extra Buttons in Advanced Mode

The Extra Buttons declared in the configuration file Cfg.pl appear directly below the "default" buttons in W2H's Main Window. The order in which they appear corresponds to the declaration order. A typical entry in Cfg.pl for Extra Buttons looks like:

@EXTRA_BUTTONS = (
    'News'         => "http://$SERVER/menu/cgi-bin/w2h-public/w2h.news",
    'Databases'    => "http://$SERVER/menu/cgi-bin/w2h-public/w2h.database",
    'Batch-Queues' => "http://$SERVER/$BIN_ROOT/w2h.list-batch",
    'Dummy'        => 'http://www.whatever.com',
    );

Each button declaration has the form:

"<button-label>"  =>  "<button-URL>"

Several button declarations are comma separated. Clicking on one of those buttons results in opening a new window and loading there the contents of the specified URL.

Note, that the amount of characters used in the button label affects the width of all buttons in that column of buttons in the Main Window, and long labels shift the Application List to the right and could cause its scrollbar to disappear

Extra Buttons in Simple Mode

In W2H's Simple Mode, there is a Show Extra Items tab at the top of the Simple Mode Window, whenever Extras are defined. On a click on that tab, a small window appears, displaying the Extra Buttons and Extra Items. The size of that window increases with the amount of the Extra Buttons/Items.

Extra Items in Advanced Mode

Since of W2H version 3.0 in addition to the Extra Buttons you have the possibility to specify arbitrary HTML code, so called Extra Items.

Special support is there for creating <IMG>s with or without hyperlink.

The idea to this arose because we wanted to have a graphical representation of the user's disk quota in the Main Window. For this we developed a CGI script (optional for W2H), that queries the user's quota and returns a GIF-image representing the found data (details how to make the necessary adoptions of this CGI script for your site later).

An Example for the definition of the Extra Items in Cfg.pl is:

@EXTRA_ITEMS = (
        "SRC=\"http://$SERVER$DOC_ROOT/icons/contact.jpg\" WIDTH=75 HEIGHT=20"  
              => "http://industry.ebi.ac.uk/w2h/",
        ´SRC="http://www.dkfz-heidelberg.de/menu/w2h/icons/contact.jpg"´
              => ""
  );

This shows in 2 rows below the optional Extra Buttons the two JPEGs, where the first is a hyperlink pointing to http://industry.ebi.ac.uk/w2h/. To have more then 1 image in one row, you can enclose the definition in "[" and "]" (perl references to an array). Example:

@EXTRA_ITEMS = (
     "SRC=\"http://$SERVER$BIN_ROOT/extras/w2h.showquota" .
     "?WD=\$escaped_working_dir&USER=\$user\" WIDTH=193 HEIGHT= 31"  
            => '',
     [
        "SRC=\"http://$SERVER$DOC_ROOT/icons/contact.jpg\""  
              => "http://industry.ebi.ac.uk/w2h/",
        "SRC=\"http://$SERVER$DOC_ROOT/icons/contact.jpg\""  
              => "",
     ]
  );

Here you have 2 rows of Extra items:

row 1:	the result of the CGI-script `w2h.showquota` (must have the `Content-Type: image/*`).
row 2:	2 JPEGs, with and without hyperlink

Note: If you specify the WIDTH and the HEIGHT of the image, Netscape is able to render the <TABLE></TABLE> dimensions surrounding the images before these images are loaded. This is especially important when the image is created by a CGI script like in our w2h.showquota example, because the response of this script may take a while.

In addition to specify images, it is also possible to specify "free" HTML code. Example:

@EXTRA_ITEMS = (
        ""    => "<H3>Text with " .
                 "<BLINK><a href='http://genome.dkfz-heidelberg.de/w2h/' " .
	         "target='blink_window'><font color='#0000ff'>Anchor" .
	         "</font></a></BLINK>.</H3>" 
  );

If you specify an empty string ("") before the => sign, everything after it is regarded as "pure" HTML and is displayed within a <TABLE></TABLE> environment. You could even specify an <APPLET> tag.

Sometimes it may be necessary/desired to pass the current user-id or the current working-directory to the URL defined in Extra Items. For this there are a few specifications (placeholders), which will be replaced by W2H during run-time with the current values. Currently W2H understands the following placeholders:

$user : current user ID

$working_dir : current working-directory

$escaped_working_dir : current working-directory. The characters are escaped (´/´ => ´%2f´) to be able to use it in a URL specification.
In the following example the CGI script is w2h.showquota is fed with the current user-id and working-directory:

`$user`	: current user ID
`$working_dir`	: current working-directory
`$escaped_working_dir`	: current working-directory. The characters are escaped (´/´ => ´%2f´) to be able to use it in a URL specification.

@EXTRA_ITEMS = (
     "SRC=\"http://$SERVER$BIN_ROOT/extras/w2h.showquota" .
     "?WD=\$escaped_working_dir&USER=\$user\" WIDTH=193 HEIGHT= 31"  
            => ''
               );

Please note the use of ´\´ (backslash): all internal ´"´ (double-quotes) must be "backslashed". The same is true for the placeholders like \$userid. Otherwise they wouldn't be passed to the extra-item-subroutine in W2H. Config-variables like $SERVER must NOT be "backslashed" because their interpretation is done by perl like everywhere else in Cfg.pl. If you don't use other variables from Cfg.pl you can also use single-quotes instead of double-quotes as delimiters for the specification of the Extra Button/Item. Then you don't have to "backslash" internal double-quotes and placeholders, e.g:

@EXTRA_ITEMS = (
     'SRC="http://foo.bar/cgi-bin/extras/w2h.showquota' .
     '?WD=$escaped_working_dir&USER=$user" WIDTH=193 HEIGHT= 31'  
            => ''
               );

or also:

@EXTRA_ITEMS = (
     "SRC=\"http://$SERVER$BIN_ROOT/extras/w2h.showquota" .
     '?WD=$escaped_working_dir&USER=$user" WIDTH=193 HEIGHT= 31'  
            => ''
               );

The Quota Bar example

As one example application W2H comes with a "quota-bar" image. This example you can find in the extras subdirectory (w2h.showquota, quota_bg.gif). You can activate the quota-bar in W2H by specifying in Cfg.pl:

@EXTRA_ITEMS = (
     "SRC=\"http://$SERVER$BIN_ROOT/extras/w2h.showquota" .
     '?WD=$escaped_working_dir&USER=$user" WIDTH=193 HEIGHT= 31'  
            => ''
               );

This lengthly definition creates a non-hyperlink image below the buttons in the Main Window. This image is created by the CGI script w2h.showquota. The script is fed with the current user-id and the user's current working-directory (see the placeholder section for details how to do this).

Unfortunately this CGI script will probably not work right away:

It requires the PerlMagick extension to perl5.002
The script must be adapted to the local quota system

PerlMagick is an optional perl module available from http://www.imagemagick.org/www/perl.html which makes libMagick, a graphic tools library from the ImageMagick package, usable from perl.

If you use the Postscript to GIF conversion in W2H you possibly already have installed libMagick, because the "convert" utility used for the conversion task is part of the ImageMagick family, too. Please look at the installation manual for PerlMagick for details.

The adoption of w2h.showquota should not be too complicated. What needs to be adapted is the subroutine, that returns the quota values in a special format after querying them from the system. Please look at the comments in that script for details.

P.Ernst@dkfz-heidelberg.de

Last modified: Fri Dec 29 14:44:15 2000