Clickmap and mouseover support


Welcome     Gallery     Handbook


Manual page for Clickmap_and_mouseover_support(PL)

Clickmaps and mouseover labels

Clickmaps (clickable image maps) allow browser users to click on a region in a graphic, which acts as a hyperlink to a new web page. Mouseover labels allow browser users to move the mouse over a data point or region (without clicking) and see a text bubble appear to give additional information.

Ploticus 2.03+ can generate either server-side or client-side map files to accompany images (PNG, JPEG, or GIF); version 2.04+ supports clickable mapping in SVG. Version 2.11+ supports mouseover text labels via client-side maps for PNG, JPEG, or GIF images.

You can map pie slice labels , bars , scatterplot points , annotations , arbitrary rectangular regions , legend entries , and the plotting area (either as a grid, or in its entirety).


Examples

A number of live examples are provided below.

Server-side maps, client-side maps, and SVG

  • Server-side maps are used with image formats (PNG, GIF, JPEG). To generate a server-side map, use the -map option. The map coordinates and URLs reside in a separate file that accompanies the image file. Some web servers do not enable these by default.
  • client-side maps are also used with image formats (PNG, GIF, JPEG). They support mouseover text labels. To generate a client-side map, use the -csmap option. The map coordinates, URLs, and/or labels reside in the HTML that is loading the image. In dynamic content situations, the -mapfile stdout option may be used to dump the map information to standard output. Client-side maps are not supported by earlier browser versions.
  • SVG clickable regions are embedded directly into the SVG result and are enabled using the -map option.


Mouseover text labels

Mouseover text bubbles are done in a similar way to clickmaps, for most of the same types of plots. You must use a client-side image map (-csmap) to accompany a PNG, GIF, or JPEG image. Mouseover may be done alone or with clickability and URLs. In plotting procs, mouseover text bubble messages are specified similarly to URLs using an attribute called clickmaplabel. In situations where URLs are generated by way of embedded @variables, the text messages should be generated that way too. Here's a gallery example that uses a client-side imagemap to implement mouseover text labels (move your mouse over the bars).


Generating map files

Map generation is triggered by the presence of the -map or -csmap command line option. If these aren't specified, then no map will be generated.

You can use the -mapfile command line option (or proc page equivalent) to explicitly name your map file. Using -mapfile stdout will dump the map to standard output which can be useful in dynamic content situations. If -mapfile is not specified, the map file will have the same name as the accompanying graphic result file, except with a .map suffix.

Usage examples:

pl -png -map -prefab pie ...
pl -png -map pie3.pl
pl -png -csmap pie3.pl
pl -svgz -map results4.pl


Linking an HTML page with the generated image map

In your web pages, you can use the following HTML construct to associate a server-side map file with an image:

    <a href="mypic.map"> <img src="mypic.png" ismap > </a>

Here's an HTML example that uses an embedded client-side map for an image:

   <map name="map1">
   ... the map content that pl generates will go here ...
   </map>
   <img src="mypic.png" usemap="#map1">

Note: When ploticus generates a client-side map, it leaves off the opening <map> and closing </map> tags.

For SVG, no special action is necessary; use the normal construct.


Troubleshooting

If the -debug command line option is used the mapped regions will be displayed in bright green. If -debug is used in X11 mode, the regions are displayed but no map file is generated.

Note that if two generated mapped regions overlap, they are stacked in the order generated (the last generated is on "top").


Specifying URLs and/or mouseover labels

Ploticus will need to know how to build the URLs and/or mouseover labels that will be present in the image map result. For clickmaps, you will need to supply URLs (or arrange for URLs to be built from data fields) in your script or prefab, usually through an attribute called clickmapurl. For mouseover text messages, you will need to supply the text messages or arrange for them to be built, usually through an attribute called clickmaplabel.


..for pie graphs, bar graphs, and scatterplots

Use proc pie / bars / scatterplot attribute clickmapurl to specify a URL template. The template may contain data field references prefaced by two at-signs (@@). For example:
	clickmapurl: http://abc.com/mycgi?id=@@3
	clickmaplabel: @@4
would generate a URL for each pie slice label, bar, scatterplot point, etc., using the value in data field 3 for each. Mouseover text label will be the contents of data field 4 (this will only have an effect if client-side image map is being generated).


..for annotations and arbitrary rectangles

Use proc annotate or proc rect attribute clickmapurl to specify a URL and/or mouseover label explicitly. For example:
	clickmapurl: http://abc.com/docs/aboutpets.html
	clickmaplabel: A complete description of how to care for your new pet



..for legend entries

Embed a URL into the legendlabel attribute (or if you are using proc legendentry the label attribute). Use this format: url:url label
Mouseover labels are not supported for legend entries.
See this example: clickmap_leg


..for the plotting area to be a single region

Use proc areadef attribute clickmapurl to specify a URL. XVAL and YVAL do not apply. Use clickmaplabel to specify a mouseover label.


..for grid regions within the plotting area

Use proc areadef attribute clickmapurl to specify a URL template. The template should contain special symbols @@XVAL and/or @@YVAL. For example:
	clickmapurl: http://abc.com/mycgi?x=@@XVAL&y=@@YVAL
Then use proc axis attribute clickmap for either the X axis, the Y axis, or both.
  • For a clickmap responding to different values in X, the above URL template should contain @@XVAL, and set proc xaxis attribute clickmap: grid.
  • For a clickmap responding to different values in Y, the above URL template should contain @@YVAL, and set proc yaxis attribute clickmap: grid.
  • For a clickmap responding to different values in X and Y, the above URL template should contain both @@XVAL and @@YVAL, and set proc xaxis attribute clickmap: xygrid and proc yaxis attribute clickmap: xygrid.
The mapped regions will be centered around stubs. Stub values will be substituted into the URL template as XVAL and YVAL. These stub values will use the default format (not necessarily the displayed stub format) for the particular scale unit 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 clickmapextent attribute.
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:
	#proc xaxis
	stubs: inc <whatever>
	clickmap: grid
	axisline: no
 	tics: no
	stubomit: *
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. Here's a gallery example that illustrates.


To set a default URL for the entire image

Use proc page attribute clickmapdefault to specify a default URL that will be invoked if the mouse click is not in a defined region.


Notes:

Embedded spaces and newlines that turn up within URLs will be converted to underscores.

Grid mapping may not be used with more than one plotting area per image.


Examples

Most of the following examples have been run with -debug 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.


clickmap_pie

Click on pie slice labels.



Click here to see a gallery example that uses a client-side imagemap with mouseover text labels (but no URLs)





clickmap_annot

Click on annotations.


clickmap_leg

Click on legend entries.


clickmap_area2

Mapped plotting area grid. Numeric in X and Y. Click on plotting area. To try the SVG equivalent click here.


clickmap_area3

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.


snpmap1

Mapped plotting area grid. Numeric in X; categories in Y. Note that the mapped grid (Y) is influenced by stubslide.


colorgrid

Data points are mapped. Click on any data point.


clickmap_area

Mapped plotting area grid. Months in X, numeric in Y. Note that month format is controlled using proc axis clickmapvalformat.


clickmap_log

Mapped plotting area grid in Y. Log example. Click on plotting area.


clickmap_time2

Mapped timeline bars.


clickmap_mouse

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.


clickmap_hit

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.


data display engine  
Copyright Steve Grubb


Markup created by unroff 1.0,    April 11, 2003.