Simon Taylor


HTML::Tooltip::Javascript - Provides a perl interface for easy use of Walter Zorn's javascript tooltip library (versions prior to 4.0). See


    use HTML::Tooltip::Javascript;

    my $tt = HTML::Tooltip::Javascript->new(
        javascript_dir => '/javascript/',
        options        => \%default_options,

    # In HTML output ...

    my $tip1 = $tt->tooltip("Tip", \%options);
    print qq(<a href="/example/" $tip1>Example</a>);

    # Output the script tag that refers to the Javascript tooltip
    # library.  It's essential that this is printed after all other
    # tooltip related output.

    print $tt->at_end;

    # ... end HTML here


This perl module provides an easy interface to Walter Zorn's GPLed Javascript tooltip library (versions prior to 4.0). For further information on the Javascript library see

On a web page, a tooltip is a box of text and/or images that pops up when the mouse hovers over an image, link, some text or an area of the page (div tag). Walter Zorn's library allows great control over these boxes including changing colors, borders, fonts, images, delay (how fast the box pops up), alignment, shadows and more.

This perl module makes the Javascript tooltip library simple to use from a CGI aspect, allowing you to set defaults so that all your tooltips appear the same, and keeping the amount of code you have to write to a minimum.


For those who don't like reading doco, here's a working example. Make sure you've copied wz_tooltip.js into a web enabled directory.

    use strict;
    use warnings;
    use CGI;
    use CGI::Carp qw(fatalsToBrowser); # Comment this out in production
    use HTML::Tooltip::Javascript;

    my $q = CGI->new();

    my $tt = HTML::Tooltip::Javascript->new(
        # Relative url path to where wz_tooltip.js is
        javascript_dir => '/javascript/',
        options        => {
            bgcolor     => '#EEEEEE',
            default_tip => 'Tip not defined',
            delay       => 0,
            title       => 'Tooltip',

    my $tip1 = $tt->tooltip("Walter Zorn's page", {fontsize => '30px'});
    my $tip2 = $tt->tooltip("CPAN");
    my $tip3 = $tt->tooltip();

    print $q->header;
    print $q->start_html;

    print <<"EOT";
    <a href="" $tip1>Walter Zorn</a><BR>
    <a href=""    $tip2>CPAN</a><BR>
    <a href=""   $tip3>Perlmeme</a><BR>

    print $tt->at_end;
    print $q->end_html;



    my $tt = HTML::Tooltip::Javascript->new(
        javascript_dir => '/javascript/',
        options        => \%default_options,

This method create a new HTML::Tooltip::Javascript object. The parameters are optional.


This defines the relative url to the wz_tooltip.js file. For example, if you have put the wz_tooltip.js file in a 'javascript' directory under your document root, then you would use:

    javascript_dir => '/javascript/'

The default is /.


The hash of options defines the options available in Walter Zorn's library, but with more user-friendly names. It also allows the definition of default text for the tooltip box. The options available are:

    option           javascript option
    -------          ------------------
    above            T_ABOVE
    bgcolor          T_BGCOLOR
    bgimg            T_BGIMG
    borderwidth      T_BORDERWIDTH
    bordercolor      T_BORDERCOLOR
    default_tip      (none)
    delay            T_DELAY
    fix              T_FIX
    fontcolor        T_FONTCOLOR
    fontface         T_FONTFACE
    fontsize         T_FONTSIZE
    fontweight       T_FONTWEIGHT
    function         (none)
    left             T_LEFT
    above            T_ABOVE
    offsetx          T_OFFSETX
    offsety          T_OFFSETY
    padding          T_PADDING
    shadowcolor      T_SHADOWCOLOR
    shadowwidth      T_SHADOWWIDTH
    static           T_STATIC
    sticky           T_STICKY
    title            T_TITLE
    titlecolor       T_TITLECOLOR
    width            T_WIDTH

When defined in new, the options will be applied to each tooltip, unless the call to tooltip() specifically redefines that option.

The default_tip is the text that will be used if no text is provided in the call to tooltip().

The function option is used if the text you pass in as the tip is actually a call to a javascript function. The javascript function must return text to output in the tooltip.


    my $tip1 = $tt->tooltip("Tip", \%options);

This method returns the HTML to be inserted into the HTML element for which the tooltip is to be displayed.

For example, to output a tooltip for a link:

    my $tip1 = $tt->tooltip("Example Tip", {fontcolor => 'blue'});
    print qq(<a href="/example/" $tip1>Example</a>);

This would output a link with text 'Example', and when the mouse pointer hovers over the link, a popup box with the words 'Example Tip' in blue would appear.

Any options passed into to the tooltip() method will overwrite the values provided in the new method. However, options provided in the new method will be inherited unless specifically undefined in the tooltip method.


    print $tt->at_end;

This method outputs the html to include Walter Zorn's script. It must be output after all tooltip related output. We recommend printing the output of this method at the end of the html, just before the close BODY tag (hence the name at_end()).


Walter Zorn's site states that the library supports the following browsers:

Linux: Konqueror 3, Browsers with Gecko-Engine (Mozilla/Firefox, Netscape 6, Galeon), Netscape 4 and 6, Opera 5 and 6.

Windows: Netscape 4, Gecko Browsers, IE 4, 5.0, 5.5 and 6.0, Opera 5,6,7.

Other: The equivalent browsers on other Operating Systems should also work as expected.


These explanations are based on Walter Zorn's own documentation at, except for 'default_tip' and 'function' which are perl only options.


Places the tooltip above the mousepointer. Value: true. Additionally applying the offsety command allows to set the vertical distance from the mousepointer.


Background color of the tooltip.


Background image.


Width of tooltip border. May be 0 to hide the border.


Border color.


Used in the new() method only. Provides default text to be used in a tooltip when no other text is defined.


Tooltip shows up after the specified timeout (milliseconds). A behavior similar to that of OS based tooltips.


Fixes the tooltip to the co-ordinates specified within the square brackets. Useful, for example, if combined with the sticky command.


Font color.


Font face / family.


Font size + unit. Unit inevitably required.


Font weight. Available values: 'normal' or 'bold'.


Used to indicate that the text is actually a call to a javascript function.


Tooltip positioned on the left side of the mousepointer. Value: true. A suggested use is also setting above to true when using this option.


Horizontal offset from mouse-pointer. To center the tooltip below (or above) the mousepointer, apply the value -tooltipwidth/2. In wz_tooltip.js itself, width is preset to 300.


Vertical offset from mouse-pointer.


Inner spacing, i.e. the spacing between border and content, for instance text or image(s).


Creates shadow with the specified color. Value in single quotes. Shadow width (strength) will be automatically processed to 3 (pixels) if no global shadow width setting can be found in in wz_tooltip.js, and the concerned html tag doesn't contain a shadowwidth command.


Creates shadow with the specified width (strength). Shadow color will be automatically processed to '#cccccc' (light grey) if neither a global setting in wz_tooltip.js nor a shadowcolor command can be found.


Like OS-based tooltips, the tooltip doesn't follow the movements of the mouse-pointer. Value: true


The tooltip stays fixed on it's initial position until another tooltip is activated, or the user clicks on the document. Value: true


Title. Text in single quotes. Background color is automatically the same as the border color.


Color of title text. Preset in wz_tooltip.js is '#ffffff' (white).


Width of tooltip.


Nothing would be possible in the open source world without people like Walter Zorn providing elegent, stable, well documented and available code, like the Javascript tooltip library. Thanks Walter!


See and


You cannot use Javascript to dynamically change the contents of the tooltip. What you put in the HTML is what you get in the tooltip. This is a feature of the underlying Javascript library and not the Perl module.


Becky Alcorn, Simon Taylor. Unisolve Pty Ltd <>


Copyright (C) 2004,2006 by Unisolve Pty Ltd

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available.

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 236:

You forgot a '=back' before '=head2'

Around line 271:

'=item' outside of any '=over'

Around line 367:

You forgot a '=back' before '=head1'