## Clickmap and mouseover support

Version 2.32

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 PNG, JPEG, GIF, or SVG graphic, which acts as a hyperlink to a new web page.`` Mouseover labels (also refered to as "tooltips" or "pop-up text bubbles") allow browser users to move the mouse over a data point or region (without clicking) of a PNG, JPEG, GIF, or SVG graphic, and see a text bubble giving additional information (a powerful annotation technique).``

Ploticus allows you to do these types of things in bar graphs, scatterplots, pie graphs, annotations, any arbitrary rectangular region, or the plotting area as a grid or in its entirety.``

## Examples

A number of live script examples are provided below.``

Here's a prefab example: 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 \
       clickmapurl="http://abc.com/cgi-bin/showcase?caseid=@2" \
       clickmaplabel="@3"  -csmap -mapfile stdout

## What are the various kinds of image maps?

Server-side maps may be used with PNG/GIF/JPEG (the mapping info is located in a separate file).`` Some web servers do not enable these by default.`` client-side maps may also be used with PNG/GIF/JPEG; the map info resides in the HTML that is loading the image.`` Client-side maps are not supported by older browser versions.`` SVG clickable regions are embedded directly into the SVG result.``

## Mouseover text labels

Mouseover text bubbles (sometimes called "tooltips") are done in a similar way to clickmaps, for most of the same types of plots.`` You must generate a client-side image map (-csmap or -csmapdemo) to accompany a PNG, GIF, or JPEG image. For SVG, you must use the -map or -csmap command line argument (doesn't matter which) even though no separate map file will be generated.`` 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` or `clickmaplabeltext`. 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).`` Here's an SVG mouseover example.``

## Generating maps

Specify the command line option -map or -csmap (use -mapdemo or -csmapdemo for debugging / development).``

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, client-side will default to `stdout` while server-side will be written to a file having the same name as the accompanying graphic result file except with a `.map` suffix.``

Usage examples:

  `pl -png -csmap -mapfile stdout pie3.pl`
  `pl -png -map -prefab pie ...`
  `pl -png -map pie3.pl`
  `pl -svgz -map results4.pl`

## Incorporating the generated image map into an HTML page

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

The -mapdemo or -csmapdemo command line options may be used to show where the mapped are; they will be outlined in green. Further, -csmapdemo when used with -png, -jpg of -gif will generate a complete HTML chunk linking the output image with the map.``

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 lables per plot job.`` Max length of a clickmap url or mouseover label (after variable evaluation) is 250 characters.``

## 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 `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:

      	clickmapurl: http://abc.com/mycgi?id=@@3
      	clickmaplabel: @@4

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

## ..for 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:

      	clickmapurl: http://abc.com/docs/aboutpets.html
      	clickmaplabel: A complete description of how to care for your new pet

## ..for legend entries

  In scripts embed a URL into the `legendlabel` attribute (or if you are using proc legendentry 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: clickmap_leg

## ..for the plotting area to be a single region

  In scripts, 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

  In scripts, 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

  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.

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

## Script examples

Most of the following script examples have been run with -mapdebug 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 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)

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, `` `` August 23, 2005.