WebFOCUS Newsletter Spring 2006 - Dynamic Tool Tip on a WebFOCUS Graph

In my experience working with many customers, it is always interesting and challenging to come up with new and innovative ideas that our products do not accomplish directly out of the box. In this article, I will go over one such example. The technique discussed here is a dynamic tool tip that was developed for one of our customers. This example of a dynamic tool tip can dynamically display information from a database in a JavaScript "callout" or an "ALT" message pop-up box.

Imagine you need to display more information in a report (Screen 1), but you do not have the screen real estate to do so. This tool tip technique, which can be applied to reports and graphs, will certainly do the job.

Screen 1

The first step is to extract the particular piece of data needed from the required field. You can do this with a simple table request and selection criteria. Depending on the data source being accessed, holding the data output requires a bit of tweaking. I found that the following code works best with Microsoft SQL and VARCHAR fields.

TABLE FILE COMMA
PRINT DESCRIPTION/A255
WHERE DESCKEY EQ 1
ON TABLE HOLD FORMAT ALPHA
ON TABLE SET HOLDLIST PRINTONLY
END
-RUN
-READ HOLD &THETOOLTIP.255

The key components to this request are the reformatting of the DESCRIPTION field with A/255, using FORMAT ALPHA, and HOLDLIST PRINTONLY. The combination of this FOCUS syntax ensures that the descriptive text is extracted correctly. Using a -READ will assign the text value to an AMPER variable that can be referenced in the FOCEXEC. Now that we have our dynamic descriptive tool tip assigned to an AMPER variable, the next step is to create a method for displaying it. I will start out with the simplest and most direct method for this process. Web browsers have settings in which you can turn off the loading of images.

Well, the HTML <IMG > tag "ALT" property was originally designed to allow individuals to visually picture what was missing. Why not exploit this functionality and use it to display the tool tip? This simple technique works well on a chart, not gauges. It will display the tool tip only when hovered over a measure. It will not show the default data value of the graph object when enabled. The advantage to this method is that no third-party JavaScript is required. The second more advanced example will cover these shortcomings.

The code to use within your graph request to achieve this (Screen 2) is as follows:

TYPE=REPORT,
  GRID=OFF,
  FONT='TIMES NEW ROMAN',
  SIZE=10,
  BACKCOLOR='NONE',
  STYLE=NORMAL,
  JAVASCRIPT=void(0),
  ALT='&THETOOLTIP',$

Screen 2

The combination of the JAVASCRIPT and ALT properties in the WebFOCUS style sheet create a mock drilldown. The JAVASCRIPT function void(0) does nothing when clicked, which will serve the purpose of only displaying the tool tip when one hovers over the content in the graph. It is important to note that the ALT property is not used until a drilldown style sheet property such as FOCEXEC or JAVASCRIPT is added.

The more advanced method requires some third-party JavaScript that you can embed into your FOCEXEC procedure. I searched the Internet and found a JavaScript that displays a "callout," which follows the mouse as you hover over an image. If desired, you can modify the .css file and the .js file to enhance your tool tip.

I modified the .js file to display the callout when the graph background is clicked and disappear when clicked again. This example has two methods available, one which works well with gauges. In the first method the tool tip only displays when you click on the gauge and hides when you click on it again. In the second method the tool tip appears when you hover over a graphic of your choice (Screen 3).

Screen 3

The FOCEXEC begins with references to the client side JavaScript and a Cascading Style Sheet used for this example.

-HTMLFORM BEGIN

<html>
<head>
<link href="/approot/covansys/tooltip/the_style.css" 
rel="stylesheet" type="text/css">
<script src="/approot/covansys/tooltip/the_script.js" 
type="text/javascript"> 
</head>
<body>
<script>
var thetext = "&THETOOLTIP"
</script>

<img src="/approot/covansys/tooltip/help.gif" 
onmouseover="ddrivetip(thetext, 300); style.cursor='hand'";
onmouseout="hideddrivetip()">
</body>
</html>

-HTMLFORM END
-RUN

Setting the value of the AMPER variable to a JavaScript variable is an important step. It will ensure that any text that contains special characters, such as quotes, is passed correctly to the ddrivetip function. The ddrivetip function is found in the .js file. Now using the GRAPH API, which contains the following methods, I am able to create a href to call the JavaScript function.

setURL( getGaugeBackground(),
"javascript:ddrivetip(thetext,300); void(0);" );
setToolTipDisplay(false);
-* prevents empty ALT box from displaying
-*Custom ALT Setting for GRAPH API 
command set is not available

Please keep in mind that these gauges were developed for the customer and have had the addition of many GRAPH API commands to achieve the specific look and feel. Your representation may vary. Now if you wanted to use this method on another type of chart you can use the getChartBackground() method (Screen 4).

Screen 4

As you can see, although not directly out of the box, it is possible to do anything with WebFOCUS. In my next article, I will show you how to plot dynamic graph data points and how to dynamically change the graphing series based on those points. And that's an important step when creating graphs with dynamic data points.