.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: clickmap and mouseover 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>Clickmap and mouseover support</h2></td>
  <td align=right>
  <small>
  <a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  Version 2.30
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH Clickmap_and_mouseover_support PL "26-AUG-2004   PL ploticus.sourceforge.net"

.SH Clickmaps and mouseover labels
.LP
\fBClickmaps\fR (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.
\fBMouseover labels\fR allow browser users to move the mouse over a data point or region (without clicking) 
of a PNG, JPEG, GIF, or SVG graphic,
and a text bubble appears giving additional information (a powerful annotation technique).
.LP
Bars, scatterplot points, and pie slice labels may be mapped.
Script writers can also map annotations, arbitrary rectangular regions, or
the plotting area, either in its entirety or as a grid.  

.ig >>
<br><br><br>
.>>

.SH Examples
A number of
.ig >>
<a href="#examples">
.>>
\0live script examples
.ig >>
</a>
.>>
are provided below.
.LP
Here's a 
.ig >>
<a href="prefabs.html">
.>>
\0prefab
.ig >>
</a>
.>>
example: Suppose \fCmyfile.dat\fR has values in field 1, case IDs in field 2, and descriptive strings 
in field 3.  Assume that we have a URL that accepts case IDs as a user variable.  We could generate a bar graph
with click-thru and mouseover popup text bubble support by using this command: 
.nf
  pl -prefab bars  data=myfile.dat  delim=tab  y=1 \\
   clickmapurl="http://abc.com/cgi-bin/showcase?caseid=@2" \\
   clickmaplabel="@3"  -csmap -mapfile stdout
.fi

.ig >>
<br><br>
.>>

.SH What are the various kinds of image maps?
.LP
.ig >>
<a href="http://hoohoo.ncsa.uiuc.edu/docs/tutorials/imagemapping.html">
.>>
\0Server-side maps
.ig >>
</a>
.>>
may be used with image formats, and the mapping info is located in a separate file.
Some web servers do not enable these by default.
.ig >>
<a href="http://www.netscape.com/assist/net_sites/html_extensions_3.html">
.>>
\0client-side maps
.ig >>
</a>
.>>
may also be used with image formats, and
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.

.ig >>
<br><br><br>
.>>
.SH 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 (\fB-csmap\fR or \fB-csmapdemo\fR) to accompany a PNG, GIF, or JPEG image.  
For SVG, you must use the \fB-map\fR or \fB-csmap\fR 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 \fCclickmaplabel\fR.  In situations where URLs are generated by way of embedded 
@variables, the text messages should be generated that way too.
Here's a 
.ig >>
<a href="../gallery/cs_mouseover.htm">
.>>
\0gallery example
.ig >>
</a>
.>>
that uses a client-side imagemap to implement mouseover text labels (move your mouse
over the bars).
Here's 
.ig >>
<a href="../gallery/svg_mouseover_examp.html">
.>>
\0an SVG mouseover example.
.ig >>
</a>
.>>


.ig >>
<br><br><br>
.>>

.SH Generating maps
Specify the command line option \fB-map\fR or \fB-csmap\fR
(use \fB-mapdemo\fR or \fB-csmapdemo\fR for debugging / development).
.LP
You can use the \fB-mapfile\fR command line option (or proc page equivalent) to explicitly name your map file.
Using \fC-mapfile stdout\fR 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 \fCstdout\fR while server-side will
be written to a 
file having the same name as the accompanying graphic result file except with a \fC.map\fR suffix.
.LP
Usage examples:
.IP \0 \0
\fCpl -png -csmap -mapfile stdout pie3.pl \fR
.br
\fCpl -png -map -prefab pie ...\fR
.br
\fCpl -png -map pie3.pl \fR
.br
\fCpl -svgz -map results4.pl\fR



.ig >>
<br><br><br>
.>>

.SH Incorporating the generated image map into an HTML page 
.LP
In your web pages, you can use the following HTML construct 
to associate a \fBserver-side\fR map file with an image:
.nf
    <a href="mypic.map"> <img src="mypic.png" ismap > </a>
.fi
.LP
Here's an HTML example that uses an embedded \fBclient-side\fR map for an image:
.nf
   <map name="map1">
   ... the map content that pl generates will go here ...
   </map>
   <img src="mypic.png" usemap="#map1">
.fi
.LP
Note: When ploticus generates a client-side map, it leaves off the opening \fC<map>\fR
and closing \fC</map>\fR tags.
.LP
For SVG, no special action is necessary; use the 
.ig >>
<a href="svg.html">
.>>
\0normal construct.
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>
.SH Troubleshooting
The \fB-mapdemo\fR or \fB-csmapdemo\fR command line options may be used to show where the
mapped are; they will be outlined in green.  Further, \fB-csmapdemo\fR when used with \fB-png\fR, 
\fB-jpg\fR of \fB-gif\fR will generate a complete HTML chunk linking the output image with the map.
.LP
Note that if two generated mapped regions overlap, they are stacked in the order generated
(the last generated is on "top").
.LP
There is an upper limitation of 500 clickmap zones / 500 mouseover lables per plot job.

.ig >>
<br><br><br>
.>>
.SH 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
.ig >>
<a href="prefab_stdparms.html#clickmapurl">
.>>
\0prefab, 
.ig >>
</a>
.>>
usually through an attribute called \fBclickmapurl\fR.
For mouseover text messages, you will need to supply the text messages
or arrange for them to be built, usually through an attribute called \fBclickmaplabel\fR.

.ig >>
<br><br><br>
.>>
.SH ..for pie graphs, bar graphs, and scatterplots
.IP \0
Use \fCclickmapurl\fR to specify a URL template.
Use \fCclickmaplabel\fR to specify a popup text label.
The template may contain 
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0data field references
.ig >>
</a>
.>>
prefaced by two at-signs (@@).
For example, script writers could specify something like this for proc bars:
.nf
	clickmapurl: http://abc.com/mycgi?id=@@3
	clickmaplabel: @@4
.fi
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.

.ig >>
<br><br><br>
.>>
.SH ..for annotations and arbitrary rectangles
.IP \0
In scripts, use \fBproc annotate\fR or \fBproc rect\fR attribute \fCclickmapurl\fR to specify a 
URL and/or mouseover label explicitly.  For example:
.nf
	clickmapurl: http://abc.com/docs/aboutpets.html
	clickmaplabel: A complete description of how to care for your new pet
.fi

.ig >>
<br><br><br>
.>>
.SH ..for legend entries
.IP \0
In scripts 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
The combined length of the url and the label should not exceed 255 characters.
.br
Mouseover labels are not supported for legend entries.
.br
See this example:
.ig >>
<a href="../gallery/clickmap_leg.htm">
.>>
\0clickmap_leg
.ig >>
</a>
.>>


.ig >>
<br><br><br>
.>>
.SH ..for the plotting area to be a single region
.IP \0
In scripts, use \fBproc areadef\fR attribute \fCclickmapurl\fR to specify a URL.
XVAL and YVAL do not apply.  Use \fCclickmaplabel\fR to specify a mouseover label.


.ig >>
<br><br><br>
.>>
.SH ..for grid regions within the plotting area
.IP \0
In scripts, 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 \0
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
.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 \0
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: *
.fi
\fBMouseover text labels\fR are not directly supported for plotting area grid, but a workaround
for doing this is to use proc bars with the \fCconstantlength\fR attribute to draw
invisible bars (use white for the color) that extend to cover the entire plotting area.
Here's a 
.ig >>
<a href="../gallery/cs_mouseover.htm">
.>>
\0gallery example
.ig >>
</a>
.>>
that illustrates.

.ig >>
<br><br><br>
.>>
.SH To set a default URL for the entire image
.IP \0
In scripts, 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 Script examples
Most of the following script examples have been run with \fB-mapdebug\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>
.>>
.ig >>
<br>

<br>
<br>
<map name=er1>
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=projstrains" coords="281,22,308,33" title="many-to-many mapping between projects and strains" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=contributed-data" coords="501,26,601,93" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=institutions" coords="343,122,438,141" title="institutions associated with investigators" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=people" coords="359,90,422,109" title="participating investigators" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=projects" coords="354,42,427,61" title="phenotyping and genotyping projects" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=assaystats" coords="149,170,233,189" title="summary statistics computed for each measurement" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=sexdiff" coords="237,66,304,85" title="sex differences computed for each measurement / strain" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=corrstrong" coords="13,106,65,125" title="correlations computed between all possible pairs of MPD measurements" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=summstats" coords="47,66,126,85" title="summary statistics computed for each measurement / strain / sex" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=assays" coords="159,122,222,141" title="description of each MPD measurement" >
<area shape="rect" href="http://aretha.jax.org/pub-cgi/phenome/mpdcgi?rtn=datamodel/tabledetails&table=strains" coords="157,26,225,45" title="mouse strains having data in the MPD" >
</map>
<img src="../gallery/er.gif" usemap="#er1">
<br>
<a href="../gallery/er.htm">Click here to see script source</a>.
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.
<br>
<br>
<br>
<br>
<h3><a href="../gallery/cs_mouseover.htm">Click here</a> to see another gallery example
that uses a client-side imagemap with mouseover text labels (but no URLs)</h3>
<br>
<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.
To try the SVG equivalent 
.ig >>
<a href="../gallery/clickmap_area2.svgz">
.>>
\0click here.
.ig >>
</a>
.>>

.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="../doc/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>
.>>
