.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
-->
</STYLE>
<title>ploticus: html clickmap support</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td>
  <table cellpadding=2 width=550><tr>
  <td><br><h2>HTML clickmap support</h2></td>
  <td align=right>
  <small>
  <a href="../doc/Welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  <a href="../doc/Welcome.html">Welcome</a> &nbsp; &nbsp;
  <a href="../gallery/index.html">Gallery</a> &nbsp; &nbsp;
  <a href="../doc/Contents.html">Handbook</a> 
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH HTML_clickmap_support PL "11-JAN-2002   PL ploticus.sourceforge.net"

.LP
.ig >>
<a href="http://hoohoo.ncsa.uiuc.edu/docs/tutorials/imagemapping.html">
.>>
\0HTML clickmaps
.ig >>
</a>
.>>
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
.ig >>
<a href="http://hoohoo.ncsa.uiuc.edu/docs/tutorials/imagemapping.html">
.>>
\0HTML click map file
.ig >>
</a>
.>>
in addition to the image file.  
.LP
Ploticus (2.02+, all builds) provides clickmap support by generating the clickmap 
file concurrently with the graphic.
Clickmap support is available for
.ig >>
<a href="pie.html">
.>>
\0pie slice labels
.ig >>
</a>
.>>
,
.ig >>
<a href="bars.html">
.>>
\0bars
.ig >>
</a>
.>>
,
.ig >>
<a href="scatterplot.html">
.>>
\0scatterplot points
.ig >>
</a>
.>>
,
.ig >>
<a href="annotate.html">
.>>
\0annotations
.ig >>
</a>
.>>
, 
.ig >>
<a href="legend.html">
.>>
\0legend entries
.ig >>
</a>
.>>
, and 
.ig >>
<a href="areadef.html">
.>>
\0the plotting area
.ig >>
</a>
.>>
(divided into subregions as a grid, or in its entirety).
A number of
.ig >>
<a href="#examples">
.>>
\0examples
.ig >>
</a>
.>>
are provided below.

.LP
In your web pages, you can use the following HTML construct 
to add clickmap support for an image:
.nf
    <a href="mypic.map"> <img src="mypic.png" ismap > </a>
.fi


.SH Generating HTML clickmaps
Clickmap generation is turned on using the
\fB-map\fR command line option.
This option may be used when generating PNG, GIF, or JPEG images.
.LP
It is also necessary to specify clickmap URL information (discussed below) in your script or 
.ig >>
<a href="prefab_stdparms.html#clickmapurl">
.>>
\0prefab
.ig >>
</a>
.>>
\0.
(If the script contains clickmap URL attributes but \fB-map\fR 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 \fC.map\fR suffix will be used.


.ig >>
<br><br><br>
.>>
.SH Troubleshooting
If the \fB-debug\fR command line option is used along with \fB-map\fR, the clickmap 
regions will be displayed in bright green.  If \fB-debug\fR is used in X11 mode, the regions
are displayed but no clickmap file is generated.

.ig >>
<br><br><br>
.>>
.SH Specifying URLs
Usually the programmer supplies URL template(s) or URLs within the script file
(eg. for pie graphs this is done within 
.ig >>
<a href="pie.html">
.>>
\0proc pie
.ig >>
</a>
.>>
; for the plotting area it is done within
.ig >>
<a href="areadef.html">
.>>
\0proc areadef
.ig >>
</a>
.>>
).   
.ig >>
<br><br><br>
.>>
.LP
\fBFor pie graphs, bar graphs, and scatterplots\fR:
.IP
Use \fBproc pie / bars / scatterplot\fR attribute \fCclickmapurl\fR to specify a URL template.
The template may contain 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0data field references
.ig >>
</a>
.>>
prefaced by two at-signs (@@).
For example: 
.nf
	clickmapurl: http://abc.com/mycgi?id=@@3
.fi
would generate a URL for each 
pie slice label, bar, scatterplot point, etc.,
using the value in data field 3 for each.
This example:
.nf
	clickmapurl: @@6
.fi
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.

.ig >>
<br><br><br>
.>>
.LP
\fBFor annotations:\fR
.IP
Use \fBproc annotate\fR attribute \fCclickmapurl\fR to specify a URL explicitly.
For example:
.nf
	clickmapurl: http://abc.com/docs/aboutpets.html
.fi

.ig >>
<br><br><br>
.>>
.LP
\fBFor legend entries:\fR
.IP
Embed a URL into the \fClegendlabel\fR attribute (or if you are using
.ig >>
<a href="legendentry.html">
.>>
\0proc legendentry
.ig >>
</a>
.>>
the \fClabel\fR attribute).  Use this format: \fCurl:\fIurl\fC  \fIlabel\fR
.br
See this example:
.ig >>
<a href="../gallery/clickmap_leg.htm">
.>>
\0clickmap_leg
.ig >>
</a>
.>>


.ig >>
<br><br><br>
.>>
.LP
\fBFor the plotting area to be a single region:\fR
.IP
Use \fBproc areadef\fR attribute \fCclickmapurl\fR to specify a URL.
XVAL and YVAL do not apply.


.ig >>
<br><br><br>
.>>
.LP
\fBFor grid regions within the plotting area:\fR
.IP
Use \fBproc areadef\fR attribute \fCclickmapurl\fR to specify a URL template.
The template should contain special symbols \fB@@XVAL\fR and/or \fB@@YVAL\fR.
For example:
.nf
	clickmapurl: http://abc.com/mycgi?x=@@XVAL&y=@@YVAL
.fi
Then use \fBproc axis\fR attribute \fCclickmap\fR for either the X axis, the Y axis,
or both.
.RS
.IP \(bu
For a clickmap responding to different values in X, the above URL template should contain
\fC@@XVAL\fR, and set \fBproc xaxis\fR attribute \fCclickmap: grid\fR.
.IP \(bu
For a clickmap responding to different values in Y, the above URL template should contain
\fC@@YVAL\fR, and set \fBproc yaxis\fR attribute \fCclickmap: grid\fR.
.IP \(bu
For a clickmap responding to different values in X and Y, the above URL template should contain
both \fC@@XVAL\fR and \fC@@YVAL\fR, and set \fBproc xaxis\fR attribute \fCclickmap: xygrid\fR 
and \fBproc yaxis\fR attribute \fCclickmap: xygrid\fR.
.RE
.IP
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
.ig >>
<a href="scaleunits.html">
.>>
\0scale unit
.ig >>
</a>
.>>
but this can be controlled using \fBproc axis\fR \fCclickmapvalformat\fR attribute.
By default the regions will stop at the plotting area boundary, 
but they can be extended (to encompass stubs for example) using \fBproc axis\fR 
\fCclickmapextent\fR attribute.
.IP
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:
.nf
	#proc xaxis
	stubs: inc <whatever>
	clickmap: grid
	axisline: no
 	tics: no
	stubomit: *

.ig >>
<br><br><br>
.>>
.LP
\fBTo set a default URL for the entire image:
.IP
Use \fBproc page\fR attribute \fCclickmapdefault\fR to specify a default URL that will
be invoked if the mouse click is not in a defined region.  

.ig >>
<br><br><br>
.>>
.LP
\fBNotes:\fR
.LP
Embedded spaces and newlines that turn up within URLs will be converted to underscores.
.LP
Grid mapping may not be used with more than one plotting area per image.

.ig >>
<a name=examples></a>
.>>

.ig >>
<br><br><br>
.>>
.SH Examples
Most of the following examples have been run with \fB-debug\fR 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.
.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_pie.htm">clickmap_pie</a><br>
<a href="../gallery/clickmap_pie.map"> <img src="../gallery/clickmap_pie.gif" ismap> </a>
<br>
.>>
Click on pie slice labels.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_annot.htm">clickmap_annot</a><br>
<a href="../gallery/clickmap_annot.map"> <img src="../gallery/clickmap_annot.gif" ismap> </a>
<br>
.>>
Click on annotations.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_leg.htm">clickmap_leg</a><br>
<a href="../gallery/clickmap_leg.map"> <img src="../gallery/clickmap_leg.gif" ismap> </a>
<br>
.>>
Click on legend entries.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_area2.htm">clickmap_area2</a><br>
<a href="../gallery/clickmap_area2.map"> <img src="../gallery/clickmap_area2.gif" ismap> </a>
<br>
.>>
Mapped plotting area grid.  Numeric in X and Y.  Click on plotting area.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_area3.htm">clickmap_area3</a><br>
<a href="../gallery/clickmap_area3.map"> <img src="../gallery/clickmap_area3.gif" ismap> </a>
<br>
.>>
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.

.ig >>
<br>
<br>
<br>
<a href="../gallery/snpmap1.htm">snpmap1</a><br>
<a href="../gallery/clickmap_snp.map"> <img src="../gallery/clickmap_snp.gif" ismap> </a>
<br>
.>>
Mapped plotting area grid.  Numeric in X; categories in Y.
Note that the mapped grid (Y) is influenced by \fCstubslide\fR.


.ig >>
<br>
<br>
<br>
<a href="../gallery/colorgrid.htm">colorgrid</a><br>
<a href="../gallery/colorgrid.map"> <img src="../gallery/colorgrid.gif" ismap> </a>
<br>
.>>
Data points are mapped.  Click on any data point.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_area.htm">clickmap_area</a><br>
<a href="../gallery/clickmap_area.map"> <img src="../gallery/clickmap_area.gif" ismap> </a>
<br>
.>>
Mapped plotting area grid.  Months in X, numeric in Y.  
Note that month format is controlled using \fBproc axis\fR \fCclickmapvalformat\fR.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_log.htm">clickmap_log</a><br>
<a href="../gallery/clickmap_log.map"> <img src="../gallery/clickmap_log.gif" ismap> </a>
<br>
.>>
Mapped plotting area grid in Y.  Log example.  Click on plotting area.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_time2.htm">clickmap_time2</a><br>
<a href="../gallery/clickmap_time2.map"> <img src="../gallery/clickmap_time2.gif" ismap> </a>
<br>
.>>
Mapped timeline bars.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_mouse.htm">clickmap_mouse</a><br>
<a href="../gallery/clickmap_mouse.map"> <img src="../gallery/clickmap_mouse.gif" ismap> </a>
<br>
.>>
Mapped plotting area grid.  Categories in X.  Note that the X stubs are (mostly) included in
the mapped regions.  This is done using the \fBproc xaxis\fR \fCclickmapextent\fR attribute.

.ig >>
<br>
<br>
<br>
<a href="../gallery/clickmap_hit.htm">clickmap_hit</a><br>
<a href="../gallery/clickmap_hit.map"> <img src="../gallery/clickmap_hit.gif" ismap> </a>
<br>
.>>
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.


.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="Welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
.>>
