Background Information
Included here is a custom builder for Portlet Factory to assist in the automatic display of images and numerical data on a page. A sample model is also included. Two images are specified and a counter (numerical) value. The counter value is used to determine which image is used - one image is used for a zero value, the other image for non-zero values. An optional tooltip (using Dojo or html title attribute) for each image is also supported.

An earlier version of this custom builder is already in use in the Connections 2.5 Files portlet, posted on this wiki here:
http://www-10.lotus.com/ldd/pfwiki.nsf/dx/Accessing_Connections_2.5_Files_using_IBM_WebSphere_Portlet_Factory

The following screenshot shows where the builder is applied. In the first instance the builder is used to display one of two images to signify the number of files in a collection. If the number is zero then the faint, grey file image is used. If the number of files is greater than zero then the double-file image is used. In each case the counter value, ie number of files in the collection, is also displayed. Likewise for the second instance which shows how many times the collection is shared with other users. If it is not shared then the image is a grey outline image, otherwise it is a green-colored image. Again, the counter value gets displayed in each case.


Builder Description
Figure 2 below shows a screenshot of the inputs for the Counter Image builder:



This custom builder is a Page Control type builder and as such puts html on a page at a specified location. Therefore, one input requirement is the target page location - for this the usual page location input fields used in other builders of this type are included.

Another required input is the counter (numerical) value. This can be a hardcoded number, a call to an Action List or method builder returning an integer or a string containing a number, or a reference to a variable that contains the numerical value. In the figure above it is a reference to a variable value.

The builder then needs to know the paths to the 2 image files - one to be displayed when the counter value is zero, the other to be displayed if the value is not zero. In the figure above the two values for are paths to .gif files stored in the project.

The next section is entitled "Tooltip Options". This is where a tooltip for each scenario (counter zero/non-zero) may be inputted. By default the 'Create Tooltips' checkbox field is unchecked and no other input fields are visible. Checking this box will result in the tooltip inputs being displayed - as shown in figure 2 above. Two types of tooltips are supported. The first is called 'Html', where the tooltip is assigned to the title attribute of a wrapping element to display the tooltip as a prompt or 'alt' string. The second supported tooltip type is called 'Dojo' and this is where the custom builder utilises the Dojo Tooltip builder, via it's API, to render the tooltip as a Dojo tooltip. See figure 3 below for examples of the two types of tooltips. Note that setting a tooltip to blank will not result in a blank tooltip - the tooltip box or bubble will not be rendered.

Optionally a couple of tooltip messages can be specified to display extra information when the mouse moves over either the image or the numerical value. The builder has two input fields for tooltip message, one for each image. If a field is left empty the tooltip container (box or speech bubble) will not be displayed. A choice of tooltip rendering is supported - either using a Dojo Tooltip or Html's title attribute.


Sample Description
The sample contains a single model which uses two instances of the Counter Image builder to display a pair of counters. One uses a zero value, the other non-zero. The first builder uses the HTML "title" attribute whilst the second uses the Dojo Tooltip builder API to display the tooltip message. The model may be run and the browser should display something similar to the following:

Figure 3 : Screenshot of sample app when executed standalone on WAS CE using Internet Explorer 8.

Notes on running the sample and prerequisites
Import the attached zip files into your Portlet Factory project using the Import WebSphere Portlet Factory Archive command. The archive file builder.zip contains the builder Java code and .bdef file. The archive file sample.zip contains a model that invokes the customer builder, as shown above. This archive also includes a html file for the page and 2 image (.gif) files.

The sample and builder were developed and tested using WebSphere Portlet Factory 7.0.0.

Note that because the builder has a dependency on the Dojo Tooltip builder, your project therefore needs to include the Dojo Ajax feature set, as shown here...

Figure 4 : Add Dojo Ajax feature set to the project