HelpBalloons Plugin

Summary

Description

Help Balloons Plugin

Description

The help-balloons plugin provides a Grails TagLib wrapper around the HelpBalloon system from Beau Scott. This plugin provides the most basic support possible to give a simple balloon help (a.k.a. Callout) facility in GSPs typically for use in intranet applications.

Installation

Execute the following from your application directory:

grails install-plugin help-balloons

The installation process copies six image files (balloon-*.png and .gif) to the images directory of your application, plus HelpBalloon.js to the js directory of your application overwriting any files of the same name.

Usage

The plugin provides two tags, the first of which is used only once within a GSP and must be placed within the <head> section of the GSPs in which you intend to use help balloons. The tag has the format:

<g:helpBalloons/>

Note that the tag has a plural name (Balloons not Balloon). This tag loads the Prototype JavaScript library (a standard part of Grails) if it has not already been loaded, and the HelpBalloon JavaScript library (included in this plugin). If your prototype library is not in the standard location and yet you would still like the hepBalloons tag to load it for you, then you may use a 'base' attribute as follows:

<g:helpBalloons base="/myApp/myDir/"/>

If you do not wish to use the standard images provided with the HelpBalloon system, you can specify the names and locations of the images to use by including attributes to the helpBalloons tag as follows:

The second tag is the helpBalloon (singular) tag which may be placed anywhere within the body of your GSP where you would like balloon help to appear. You can use as many helpBalloon tags in a GSP as you wish. An example of a 'hard coded' helpBalloon tag might be:

<g:helpBalloon title="Name" content="Names can be up to 50 characters"/>

Alternatively, an example of the helpBalloon tag used with message bundles might be:

<g:helpBalloon code="user.name" suffix=".help"/>

In this last example, the code attribute is used to look up the balloon's title within the message bundle and then the suffix is added to the code (producing user.name.help in our example) as the key to be used for looking up the content of the balloon. Since a suffix of '.help' is the default, the preceding example could have been more concisely written as:

<g:helpBalloon code="user.name"/>

By default the helpBalloon tag does not HTML encode the title or content thus allowing mark-up of the balloon's title and content. If, for safety, you would like the title and content encoding, you may use an encodeAs attribute in the helpBalloon tag, thus:

<g:helpBalloon code="user.name" encodeAs="HTML"/>

Limitations

Beau Scott, the author of the HelpBalloon JavaScript library, should be contacted with regard to any licenses that may apply to commercially distributed products using that library.

Compatibility

This plugin was written using Java version 1.6u18 and Grails version 1.3.0. The plugin includes the HelpBalloon.js library version 2.0 from Beau Scott.

If you have the localizations plugin installed, the help-balloons plugin will use the database to retrieve its titles and texts.