.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.33 Jun'06
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH Clickmap_and_mouseover_support PL "02-JUN-2006   PL ploticus.sourceforge.net"

.SH Clickmaps and mouseover labels
.LP
\fBClickmaps\fR (clickable imagemaps) allow web browser users to click on a region in
an image which behaves as a hyperlink to a new web page.
\fBMouseover labels\fR, also refered to as "tooltips" or "pop-up text bubbles",
allow web browser users to hover the mouse pointer over an image region 
and see a popup text bubble that gives additional information, which can be a powerful, clutter-avoiding 
annotation technique.
.ig >>
<a href="#examples">
.>>
\0Some live examples are shown below.
.ig >>
</a>
.>>
Ploticus supports these capabilities for various types of plots and graphs, annotations, and arbitrary rectangular regions.
There are three different strategies for achieving clickable regions and/or mouseover labels:
.IP \(bu
\fBClient side image maps\fR - best method for PNG/JPEG/GIF; allows mouseover labels; described below.
.IP \(bu
\fBServer side image maps\fR - less flexible method for PNG/JPEG/GIF when legacy browser support is required; no mouseover labels;
described below.
.IP \(bu
\fBSVG methods\fR - 
described on the
.ig >>
<a href="svg.html#mouseover">
.>>
\0ploticus SVG page
.ig >>
</a>
.>>

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

.SH Typical method
.LP
Here's a typical method for generating a PNG image with client-side image map:
.LP
1. If you want clickable regions, use the \fBclickmapurl\fR attribute in 
your plotting proc (or prefab) to specify a URL.  
Data field contents are represented in the URL constructs like this: @@2.
Example: in proc bars, you specify \fCclickmapurl: http://abc.com/cgi-bin/showall?id=@@2\fR ...
the user can click on any bar and go to the URL, where \fCid\fR will be based on data field 2.

.LP
2. If you want mouseover labels, use the \fBclickmaplabel\fR attribute in
your plotting proc (or prefab) to specify a label.
Data field contents are represented in the label using constructs like this: @@3.
Example: in proc bars, you specify \fCclickmaplabel: @@4\fR ...
the user can hover the mouse pointer over any bar and see the popup text bubble label showing 
the contents of data field 4.
.LP
3. Generate HTML like this:
.nf
   <map name="map1">
   [ Execute ploticus here.. use the -csmap command line option and
     generate an output file called eg. mypic.png ..
     It will write <area> tags to its standard output. ]
   </map>
   <img src="mypic.png" usemap="#map1">
.fi

.ig >>
<br><br>
.>>
To generate a server-side image map instead, use step 1 above, then
execute ploticus, using the -map and perhaps the -mapfile command line options.
Then incorporate your mapfile into your HTML using a construct like this:
.nf
  <a href="mypic.map"> <img src="mypic.png" ismap > </a>
.fi




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

.SH Examples
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).
A number of
.ig >>
<a href="#examples">
.>>
\0live script examples that you can try
.ig >>
</a>
.>>
are provided below.
.LP
Here's a 
.ig >>
<a href="prefabs.html">
.>>
\0prefab
.ig >>
</a>
.>>
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.
.nf
  pl -prefab bars  data=myfile.dat  delim=tab  y=1 \\
   clickmapurl="http://abc.com/cgi-bin/showcase?caseid=@2" \\
   clickmaplabel="@3"  -csmap 
.fi
Here's 
.ig >>
<a href="../gallery/svg_mouseover_examp.html">
.>>
\0an SVG mouseover example.
.ig >>
</a>
.>>
(see the
.ig >>
<a href="svg.html#mouseover">
.>>
\0ploticus SVG page
.ig >>
</a>
.>>
for more info).

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

.SH Special syntax for deploying new windows
Sometimes it is desirable to deploy a new window when the user clicks on an image.
Here's an example of how to do this in ploticus.
\fCclickmapurl: [target=new]http://abc.com/cgi-bin/show?id=@@4\fR
.ig >>
&nbsp; &nbsp;
.>>
Ploticus will pass the HTML \fCtarget=new\fR attribute through to the HTML area tags.  
You can use any standard target name.  This works with client-side maps and SVG.  New in 2.33

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

.SH Troubleshooting
A command line option (-csmap or -map) \fBmust\fR be used to turn on mapping.. the presence
of a clickmapurl or clickmaplabel attribute in a script or prefab does not by itself turn on mapping.
.LP
The \fB-csmapdemo\fR command line option may be used (in place of \fB-csmap\fR) to show the
mapped regions outlined in green.  Also, when -csmapdemo is used along with -png,
-jpg of -gif, a complete HTML chunk linking the output image with the map will be written
to standard output, as an aid to development.
.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 labels per job.
Max length of a clickmap url or mouseover label (after variable evaluation) is 250 characters.
.LP
URLs are encoded properly in 2.33+

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

.SH How it works with different graphical elements

.LP
\fBPie graphs, bar graphs, and scatterplots\fR
.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>
.>>
.LP
\fBAnnotations and arbitrary rectangles\fR
.IP \0
In scripts, use proc annotate or proc rect 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

.LP
\fBLegend entries\fR
.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>
.>>
.LP
\fBCovering the entire plotting area\fR
.IP \0
In scripts, use proc areadef 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>
.>>
.LP
\fBRegular interval regions (or a grid) within the plotting area\fR
.IP \0
In scripts, use proc areadef attribute \fCclickmapurl\fR to specify a URL template.
The template should contain special symbols @@XVAL and/or @@YVAL.
For example:
.nf
	clickmapurl: http://abc.com/mycgi?x=@@XVAL&y=@@YVAL
.fi
Then use proc axis 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 proc xaxis 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 proc yaxis 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 proc xaxis attribute \fCclickmap: xygrid\fR 
and proc yaxis 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 proc axis \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 proc axis 
\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
Mouseover text labels 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>
.>>
.LP
\fBSetting a default URL for the entire image\fR
.IP \0
In scripts, use proc page 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>
.>>
.SH Notes
.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 Live examples to try
Most of the following script examples have been run with \fB-csmapdemo\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 proc axis \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 proc xaxis \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>
<br>
<center>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
.>>
