|Clickmap and mouseover support|
Clickmaps and mouseover labels
A powerful technique in keeping web data displays uncluttered is to use tooltip popup text boxes to
display additional detail and annotation. When the user hovers their mouse over a certain region,
the relevant text is displayed as a popup textbox.
Another useful technique is to allow the user to click on certain regions of a plot and go to another
web page that has relevant additioanl information.
You can use Ploticus to generate clientside imagemaps and do these things.
1a. If you want mouseover labels, use the clickmaplabel attribute in
your plotting proc (or prefab) to specify a label.
Data field contents are represented in the label using constructs like this: @@3.
Example: in proc bars, you specify clickmaplabel: @@4 ...
the user can hover the mouse pointer over any bar and see the popup text bubble label showing
the contents of data field 4.
1b. If you want clickable regions, use the clickmapurl attribute in
your plotting proc (or prefab) to specify a URL.
Data field contents are represented in the URL constructs like this: @@2.
Example: in proc bars, you specify clickmapurl: http://abc.com/cgi-bin/showall?id=@@2 ...
the user can click on any bar and go to the URL, where id will be based on data field 2.
For very long URLs, see troubleshooting below.
2. Use HTML like this:
[ Execute ploticus here.. use the -csmap command line option and
generate an output file called eg. mypic.png ..
It will write <area> tags to its standard output. ]
<img src="mypic.png" usemap="#map1">
Not all plotting procs support this, and there are some differences depending on context... check the docs for details.
that uses a client-side imagemap to implement mouseover text labels (move your mouse
over the bars).
A number of
live script examples that you can try
are provided below.
The following prefab command generates a bar graph with both clickmap and mouseover label support.
Click-thru URLs would be built using the contents of data field 2, and mouseover labels
will be displayed using the contents of data field 3.
pl -prefab bars data=myfile.dat delim=tab y=1 \\
an SVG mouseover example.
ploticus SVG page
for more info).
Special syntax for deploying new windows
Sometimes it is desirable to deploy a new window when the user clicks on an image.
Here's an example of how to do this in ploticus.
Ploticus will pass the HTML target=new attribute through to the HTML area tags.
You can use any standard target name. This works with client-side maps and SVG. New in 2.33
Troubleshooting and Limitations
The -csmap command line option (or -map which is deprecated) must be used to turn on mapping.. the presence
of a clickmapurl or clickmaplabel attribute in a script or prefab does not by itself turn on mapping.
The -csmapdemo command line option may be used (in place of -csmap) to show the
mapped regions outlined in green. Also, when -csmapdemo is used along with -png,
-jpg of -gif, a complete HTML chunk linking the output image with the map will be written
to standard output, as an aid to development.
Note that if two generated mapped regions overlap, they are stacked in the order generated
(the last generated is on "top").
There is an upper limitation of 500 clickmap zones / 500 mouseover labels per job.
Clickmap urls associated with an areadef can be up to 255 characters in length.
Otherwise there's no length limit other then script line length.
Tooltip labels have no length limit other than script line length.
Longer URLs can be expressed (versions 2.40+) by using variables to hold
portions of the url (be sure to use double at-signs) for example:
#set queryprog = "http://abc.com/cgi-bin/query"
Ploticus allows clickmap URLs to be constructed from various elements including literal text, script variables, data field contents,
and axis values (when doing an areadef grid). Some of these elements are subject to automatic standard URL encoding, while others are not.
element URL encoding done
literal text no
script variables no
data field contents yes
axis values (grid) yes
for settings that effect url encoding.
How it works with different graphical elements
Pie graphs, bar graphs, and scatterplots
Use clickmapurl to specify a URL template.
Use clickmaplabel to specify a popup text label.
The template may contain
data field references
prefaced by two at-signs (@@).
For example, script writers could specify something like this for proc bars:
which would generate a URL for each bar using the value in data field 3 for each.
Mouseover text label will be the contents of data field 4.
See EXAMPLES above where this same thing is done with a prefab.
Annotations and arbitrary rectangles
In scripts, use proc annotate or proc rect attribute clickmapurl to specify a
URL and/or mouseover label explicitly. For example:
clickmaplabel: A complete description of how to care for your new pet
In scripts embed a URL into the legendlabel attribute (or if you are using
the label attribute). Use this format: url:url label
The combined length of the url and the label should not exceed 255 characters.
Mouseover labels are not supported for legend entries.
See this example:
Covering the entire plotting area
In scripts, use proc areadef attribute clickmapurl to specify a URL.
XVAL and YVAL do not apply. Use clickmaplabel to specify a mouseover label.
Regular consecutive intervals (or a grid) within the plotting area
This works in Ploticus scripts only.
The mapped regions will be centered around tics/stubs, and the stub values will be substituted
into the URL template (using special variables XVAL and YVAL).
Your proc xaxis/yaxis must be generating stubs (ie. it won't work with stubs: none).
In general you'll need to supply two things:
1. In your proc areadef, supply a clickmapurl attribute which specifies a URL template.
The template should contain @@XVAL and/or @@YVAL (see below). Note that two at-signs are required.
2. In your proc axis, supply a clickmap attribute (see below).
Exactly what you need to supply, depends on whether your grid is based on the X axis, Y axis, or both.
For a grid based on the X axis
(user gets different values as they click from low to high in X),
@@XVAL should be present in proc areadef's clickmapurl URL, and in proc xaxis use clickmap: grid.
For a grid based on the Y axis
(user gets different values as they click from low to high in Y),
@@YVAL should be present in proc areadef's clickmapurl URL, and in proc yaxis use clickmap: grid.
For a two-way grid involving both X and Y axes
both @@XVAL and @@YVAL should be present in proc areadef's clickmapurl URL,
and set clickmap: xygrid in both proc xaxis and proc yaxis.
These stub values will use the default format (not necessarily the displayed stub format) for the particular
but this can be controlled using proc axis clickmapvalformat attribute.
By default the regions will stop at the plotting area boundary,
but they can be extended (to encompass stubs for example) using proc axis
If you need higher (or lower) granularity than what your stubs provide, you can
invoke an additional, invisible X axis using the desired granularity like this:
stubs: inc <whatever>
Mouseover text labels are not directly supported for plotting area grid, but a workaround
for doing this is to use proc bars with the constantlength attribute to draw
invisible bars (use white for the color) that extend to cover the entire plotting area.
Setting a default URL for the entire image
In scripts, use proc page attribute clickmapdefault to specify a default URL that will
be invoked if the mouse click is not in a defined region.
Grid mapping may not be used with more than one plotting area per image.
Live examples to try
Most of the following script examples have been run with -csmapdemo to add the green
overlay showing where clickable regions are.
Try clicking on these images..
they are mapped to a live CGI program that will echo the passed parameters.
Click on pie slice labels.
Click here to see script source.
An example where proc annotate was used to create a simple
E-R diagram for a database. Entity bubbles support text annotation
that appears when the mouse hovers over them, and click-thru to
actual database table documentation. Try hovering the mouse
pointer over an entity bubble, and then click on the bubble.
Click here to see another gallery example
that uses a client-side imagemap with mouseover text labels (but no URLs)
Click on legend entries.
Mapped plotting area grid. Numeric in X and Y. Click on plotting area.
To try the SVG equivalent
Same as above, but with finer granularity.
This is done by executing an invisible X axis and an invisible Y axis
for the clickmap (in addition to the visible axes) using the automatically
determined stub increment, divided by 4.
Mapped plotting area grid. Numeric in X; categories in Y.
Note that the mapped grid (Y) is influenced by stubslide.
Data points are mapped. Click on any data point.
Mapped plotting area grid. Months in X, numeric in Y.
Note that month format is controlled using proc axis clickmapvalformat.
Mapped plotting area grid in Y. Log example. Click on plotting area.
Mapped timeline bars.
Mapped plotting area grid. Categories in X. Note that the X stubs are (mostly) included in
the mapped regions. This is done using the proc xaxis clickmapextent attribute.
Mapped plotting area grid. Datetimes in X. The datetimes are mapped in 6 hour increments,
even though stubs appear every 24 hours.
This is done by executing an invisible X axis
for the clickmap, using 6 hour increments.
Ploticus can still generate the older server-side image maps.
use step 1 above in Typical Method, then
execute ploticus, using the -map and perhaps the -mapfile command line options.
Then incorporate your mapfile into your HTML using a construct like this:
<a href="mypic.map"> <img src="mypic.png" ismap > </a>