HTML clickmap support


Welcome     Gallery     Handbook


Manual page for HTML_clickmap_support(PL)

HTML clickmaps allow a browser user to click with the mouse on an object or region in a graphic, as if it were a hyperlink to a new web page. Clickmaps work with PNG, GIF, and JPEG images, and require an HTML click map file in addition to the image file.

Ploticus (2.02+, all builds) provides clickmap support by generating the clickmap file concurrently with the graphic. Clickmap support is available for pie slice labels , bars , scatterplot points , annotations , legend entries , and the plotting area (divided into subregions as a grid, or in its entirety). A number of examples are provided below.

In your web pages, you can use the following HTML construct to add clickmap support for an image:

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

Generating HTML clickmaps

Clickmap generation is turned on using the -map command line option. This option may be used when generating PNG, GIF, or JPEG images.

It is also necessary to specify clickmap URL information (discussed below) in your script or prefab . (If the script contains clickmap URL attributes but -map isn't used, no clickmap is generated.) If two generated clickmap regions overlap, they are stacked in the order generated (the last generated is on "top"). The clickmap file will have the same name as the graphic result file, except that a .map suffix will be used.


Troubleshooting

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


Specifying URLs

Usually the programmer supplies URL template(s) or URLs within the script file (eg. for pie graphs this is done within proc pie ; for the plotting area it is done within proc areadef ).


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
would generate a URL for each pie slice label, bar, scatterplot point, etc., using the value in data field 3 for each. This example:
	clickmapurl: @@6
would take the URL for each slice, bar, etc. from data field 6. URL templates work well for typical CGI invocations where the CGI script name is constant and the parameters vary. If you have a collection of non-uniform URLs that you wish to map, they may be listed in a data field and accessed there.


For annotations:

Use proc annotate attribute clickmapurl to specify a URL explicitly. For example:

	clickmapurl: http://abc.com/docs/aboutpets.html



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
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.


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 clickmap 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: *




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.


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.


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,    January 11, 2002.