Enabling the Hover-Over-Help Feature Using JSP Custom Tags

This article introduces a presentation-tier JEE framework designed to enable the hover-over-help feature without hard coding JavaScript modules in the JSPs in your web or portal applications. The framework is packaged as a jar file for distribution and includes a server-side RESTful web service component and a set of JSP tag handlers which inserts JavaScript and Cascading Style Sheet (CSS) code into HTML files at the page rendering phrase. The targeted users are java developers who only have preliminary experience on writing JavaScript code.

1. Introduction

Mouseover is a standard JavaScript event that is raised when the user hovers the cursor over a particular HTML element on a web page.  This event has been widely used in web applications for navigation or causing an image or text to change. Hover-over-help, also called hover-over bubble, refers to the process of showing a small popup window when a mouseover event occurs in the browser. The window contains a message to either help the user to use the application or provide additional explanation and data. It is a useful feature which can make your web pages more intuitive and user-friendly and can carry more information on a single page in rich internet applications (RIAs). There are some tips and samples to enable the feature on the internet. However, they are not effective in developing large-scale web applications. Some of caveats include the following:

• The message contents are directly hard-coded in JavaScript. They are tied-coupled with graphic user interface components, such as text labels in web pages. The re-usability is low.
• If the same message needs to appear on several pages, the message and the pertaining JavaScript code have to be copied and pasted to each of these pages. It is hard to maintain these duplications in multiple places.
• The messages are designed to be static and are typically created when the page is designed. It is difficult to insert runtime data into messages on the fly.
• Portal applications are not completely supported. 

The framework introduced in this article is designed to address these issues and provides a comprehensive but easy-to-use solution to java developers who don’t have extensive JavaScript experiences. It leverages the JSP taglibary technology, the Dojo framework, and RESTful web services. Reusability in both web and portal environments, performance, and reliability are the factors that have been taken into consideration.

2. Message bubbles and messages

2.1    Message bubbles
A message bubble is a rectangle information window containing a message. Each bubble has one color-coded title compartment and one content compartment. The window is decorated by CSS definitions. The image below illustrates a sample message bubble. 

   Figure 1 – a hover-over-help message bubble

Bubbles are not viewable in the webpage until the user moves his/her mouse over action labels or images. In this case, the mouse cursor will turn into a finger-pointing hand and the pertaining bubble window will pop up near the hand.

2.2    Data structure
The message contents vary from static to dynamic considerably. However, all messages can share a common data structure, which typically consists of four parts:

•    Message ID: This is the primary key in each message, which is represented as a unique number. Given any single message ID, the framework is able to identify one and only one message.
•    Message title: This is a character string displayed in the title compartment in a bubble window.
•    Message content: This is character string that refers to the detail of a help message. The message content can contain HTML elements.
•    Color code: This is a character string representing the background color scheme of a bubble window. The value must be one of the following strings: “infor”, “data”, “warning”, or “link”.

2.3    Message types
Based on the dynamicity of the contents, we categorized all messages into three types. Each of the types is described in this section, with samples provided.

2.3.1    Static Messages
This type of message is considered static because its contents always retain the same. A static message can be the definition of a concept, the explanation of a field, or the instruction of a user action. The same messages will appear to any user on the same page when the page is visited. Valid examples include:

2.3.2    Variable Messages
These messages contain replaceable variables which are represented by tokens. A token is a non-whitespace character string surrounded by “${” and “}”. The token will be completely replaced by its actual value at the page rendering time on the server. The value is based on user data, and normally will not change for a longer-than-user-session period. From users’ perspectives, the same user will see the same message with his customized values when browsing the same page, but different users may see different messages. The following are examples of valid messages in this category:

2.3.3    Dynamic Messages
The messages in this category are the most dynamic ones and contain variables represented by tokens, as well. However, the actual values are populated based on the data associated to the user session. If it happens that a user session is shared by multiple applications, these values may be changed even without a page refresh. This situation typically occurs in portal applications where multiple portlets can access the same user session.  It is possible that the same user will read different messages at a different time on the same page. The examples are –

3. Design and implementation

In the design, messages are cached at server-side to gain the maximum performance. Two strategies have been implemented to support the hover-over-help feature for each of the message types described in the previous section.

3.1    Message caching
Messages can be persisted in a database or flat text file, but regardless of where they are physically stored, they will be loaded and cached at the web container when it starts. The framework includes a class – CacheIntializer which implements the ServerContextListener interface to perform the job. All you need to develop is your own message loader class to retrieve your messages from storage. Your class must implement the com.myuan.tags.bubblemsg.serverside.MessageLoader interface in the framework, and its name must be added as a ContextParameter in the web descriptor. Please refer to the installation section for more details.

3.2    Dojo and CSS Strategy
This strategy is designed to support static and variable messages. It can be referred as the push strategy, since help messages are embedded as html elements and pushed to users’ browsers along with the whole web page. No client-server communication is needed once the page download is done. The values will be kept the same until the page is re-loaded again. This strategy relies on a Dojo module to recognize particular “span” elements (listed in list 1) in html files. For each individual message bubble, two span elements are required. The first one represents a visible graphical component in a page, while the second one is the message bubble which isn’t visible for most of the time. When you move the mouse over the first “span” area, an action will be triggered by the browser, and a Dojo method will make the message bubble popped up (illustrated in Figure 1). The “id” attribute in the first “span” element and the “connectid” attribute in the second one are the keys to tie the pair together. These two attributes must have the same value. The value is randomly generated by the custom tags in the framework, which guarantees that the strategy can support both web and portal applications.

<span id="connectid22121585605area" class="callout" style="font-weight:bold">
    Households
</span>                                                
<span dojotype="tooltip" connectid="connectid22121585605area">
    <div class="informationWindow">
        <div class="infor">
          <div class="titleBar">Household</div>
          <div class="contentPane">A household includes all the persons who occupy a housing unit.</div>
      </div>
    </div>
</span>

Four tag handlers have been developed to support static message and variable message scenarios, respectively. At page-rendering time, the handlers can retrieve help messages from the cache, replace variable tokens in the messages if any, and create and insert value-matched “span” html elements into the web pages. The complete process is detailed in the sequence diagram in figure 2.

3.2.1    hohcsstag
This tag inserts CSS definitions in JSP pages at the rendering time. It should be placed in the page head element. In the WebSphere Portal environment, this tag should be added in the Default.jsp file.

<mt:hohcsstag />

 3.2.2    hohstatictag
hohstatictag is a custom tag built for the static message scenario. It has five attributes:

• msgid: This is the primary key used to identify a message from the cache. This attribute is mandatory.
• label: This is the text which will be associated with a mouse-over action to display the message.
• style: This is the style definition that will be used to decorate the label above. This is the place where the user could overwrite CSS arributes for the label.
• bubblestyle: This is the place where the user could overwrite CSS attributes for the message bubble.
• img: If you need to enable the hover-over on an image instead of a text label, you can use this attribute and pass the path to your image. If this attribute appears in the tag, the value in the “label” and the “style” attributes will be ignored.

A static message example --

 JSP Fragment where the hohstatictag is used –

<mt:hohstatictag msgid="1" label="Households" style="font-weight:bold"/> //text

<mt:hohstatictag msgid="1" img="/img/myimage.jpg" /> //image 

 3.2.3    hohvariabletag and hohparamtag
hohvariabletag and hohparamtag work together to support variable messages. The “hohvariabletag” has the same four attributes as the “hohstatictag” tag. One “hohparamtag” tag holds one name-value pair. The tokens in the message will be replaced with the values passed in from the hohparamtag when html elements are generated. The following is an example of how to use the custom tag.

A variable message example--

JSP Fragment where the hohvariabletag and hohparamtag are used together –

<mt:hohvariabletag msgid="2" label="<strong>My goals</strong>">
    <mt:hohparamtag paramName="rate" paramValue="<%= dao.getRate() %>"/>
    <mt:hohparamtag paramName="goal" paramValue="100"/>
</mt:hohvariabletag> 

3.2.4    hohgenerictag
This tag has been created to provide a unified API for both static and variable messages. This tag can replace the “hohstatictag” or “hohvariabletag” without any syntax change. But there will be a minor performance cost if you use this tag on the static-message scenario instead of the hohstatictag.

3.3  AJAX strategy
AJAX (Asynchronous JavaScript and XML) is a powerful web development technique in creating interactive web applications. The AJAX strategy was developed for the dynamic message scenario. It is a pull-based model, since messages are retrieved by an AJAX module at runtime from the server. This approach can guarantee that the message contains the latest data.

When a mouseover event is triggered from a web page, the AJAX module invokes the server-side RESTful web service endpoint. The server-side component picks up the correct message from the message cache, replaces all variable tokens in it with the most current user-session data, and sends the final message back to your browser in the XML format. Upon receiving the response, the AJAX module populates the pertaining information window and pops it up. The complete process is illustrated in the sequence diagram in figure 3. 

One servlet class and three custom tags have been created to support this strategy, and they must be used together in the same page.

3.3.1    HelpMessagesServiceServlet
This is an extension of the HTTPSerlvet class. It serves as the RESTful web service endpoint at the server-side. It processes the HTTP request from the client-side AJAX module, constructs the message with the latest data in user’s session, and sends the response in XML format back to the browser.

A sample response is listed below.

<mouseovermsg>
    <connectid>Household</connectid>
    <bkgdcolor>infor</bkgdcolor>
    <msgtitle>Household</msgtitle>
    <msgcontent>A household includes all the persons who occupy a housing unit.</msgcontent>
</mouseovermsg>

3.3.2    hohajaxtag
This tag inserts AJAX methods in a JSP which will be invoked by the hohdynatag below. It has two attributes. The namespace can be used to pass a portlet’s namespace into the tag in the portal environment. In a web application the value of the attribute can be left blank. The serviceurl attribute must be the valid URL for the HelpMessagesServiceServlet. In the WebSphere Portal environment, this tag should be added in the Default.jsp file.

 // Portal environment
<mt:hohajaxtag namespace="<portlet:namespace />" 
               serviceurl="/contextpath/svltpath" />  

// Web environment
<mt:hohajaxtag namespace="" serviceurl="/contextpath/svltpath" />

 3.3.3    hohdynatag and hohdynaparamtag
The hohdynatag has four attributes as same as the “hohstatictag” tag, and it will generate a “span” element. Each hohdynaparamtag establishes a mapping between one token in the message and one key used in user’s session to refer to the actual value. These mappings will be sent to the RESTful endpoint as HTTP parameters. When a user’s mouse moves over the area in a page represented by the span tag, the following events will occur sequentially at the client’s browser:

•    OnMouseOver events will be fired by the browser.
•    The Ajax method generated by the hohajaxtag will be invoked. The method will make an HTTP request to the RESTful service endpoint and will be waiting for the response.
•    Upon receiving the response, the AJAX method will parse it to get the actual help message.
•    The AJAX method will display the message bubble in the browser.

Below is a valid utilization of these tags.

<mt:hohdynatag namespace="<portlet:namespace />" msgid="6"
    lable="Definition and calculation for Retention">
  <mt:hohdynaparamtag tokenkey="first" sessionattributekey="SESSIONKEY_FIRST" />
  <mt:hohdynaparamtag tokenkey="second" sessionattributekey="SESSIONKEY_SECOND" />
</mt:hohdynatag> 

 4. Installation

 The installation procedure is fairly straight forward. After adding the jar file – MYTagLib.jar -- into the /WEB-INF/lib directory in your web project, you can use the deployment descriptor editor in RAD/RSA to complete the installation:

• Develop your own message loader class and add a context parameter with the name “BubbleMsgLoaderClass” and the value as the fully qualified name of your class.

• Create a listener. The class name is: com.myuan.tags.bubblemsg.serverside.CacheInitializer, and the class is shipped in the TagLib.jar file.

• Add the servlet class in the framework into the deployment descriptor in your web project. The servlet class is also shipped in the MYTagLib.jar.

• Define the taglib element in the /WEB-INF/web.xml file.

• Define the tag extension in your JSP pages. The <taglib-uri> and the uri directive must match. The prefix identifies the tags in the tag library within the jsp page. For example:
  
  

  <%@ taglib uri=”http://yourcompany.com/bubblemsg” prefix=”mt” %>
  

         
5    Conclusion

The framework packaged in the MYTagLib.jar can enable the hover-over-help feature in a web or portal application without adding any JavaScript/CSS code into JSP pages during the development phrase. This approach can make it simpler to create and maintain these pages. The framework has been tested in web applications running on WebSphere Application Server (WAS) 6.0 and 6.1, as well as in portal applications running on WebSphere Portal 5.1 and 6.0.