ploticus: clickmap support

## Clickmap support | Welcome Gallery Handbook |
| Manual page for Clickmap_support(PL)

Clickable maps (clickmaps) allow browser users to click on a region in a graphic, which acts as a hyperlink to a new web page.`` 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.`` For images, map info is written to a separate file.`` For SVG, the mapping information is added to the .svg / .svgz output file (so the server-side vs. client-side distinction discussed below is moot).``

You can map pie slice labels , bars , scatterplot points , annotations , 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 vs. client-side maps

There are two distinct types of clickmaps that can accompany PNG, GIF, or JPEG images: server-side maps and client-side maps . The two types are similar but have different syntaxes and are tied to an HTML web page slightly differently.`` Server-side maps have been around longer, but may need to be specifically enabled in your web server by the administrator.`` Client-side maps are more efficient, but are not supported by earlier browser versions, and may need to be embedded in the HTML of the web page loading the graphic.``

## Generating map files

To generate a server-side map, use the -map option.`` To generate a client-side map, use the -csmap option.`` For SVG, use either option.`` If neither -map or -csmap are 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; otherwise 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`

You will need to supply URL information (discussed below) in your script or prefab for hyperlink purposes.``

## HTML usage

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:

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

Note: When ploticus generates a client-side map, it leaves off the opening `<map>` and closing `</map>` tags. These tags will need to be added by the user.``

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

Image map files contain URLs so that hyperlinks can be done when a region is clicked upon.`` When ploticus generates an image map file, it needs to know how to build these URLs.`` The developer supplies URLs within the script, as a proc parameter (eg. for pie graphs this is done within proc pie ; for the plotting area it is done within proc areadef ). A URL template is usually specified rather than a hard-coded URL, so that ploticus can build a series of URLs automatically (see below).``

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

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.`` 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, `` `` December 10, 2002.