1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
|
<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/01/02 13:53:19. -->
<!-- Do not edit! -->
<STYLE TYPE="text/css">
<!--
A:link{text-decoration:none}
A:visited{text-decoration:none}
A:active{text-decoration:none}
-->
</STYLE>
<title>ploticus: html clickable imagemap 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 clickable imagemap 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>
<a href="../gallery/index.html">Gallery</a>
<a href="../doc/Contents.html">Handbook</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
<title>Manual page for HTML_clickable_imagemap_support(PL)</title>
</head>
<body>
<p>
HTML clickable imagemaps (clickmaps)
allow a browser user to click with the mouse on a region in
a PNG, GIF, or JPEG graphic, as if it were a hyperlink to a new web page.<tt> </tt>
Ploticus (2.03+) can generate either server-side or client-side maps.<tt> </tt>
<p>
Ploticus can generate an imagemap
file (a text file containing a list of regions and urls) concurrently with
the graphic. Map support is available for
<a href="pie.html">
pie slice labels
</a>
,
<a href="bars.html">
bars
</a>
,
<a href="scatterplot.html">
scatterplot points
</a>
,
<a href="annotate.html">
annotations
</a>
,
<a href="legend.html">
legend entries
</a>
, and
<a href="areadef.html">
the plotting area
</a>
(divided into subregions as a grid, or in its entirety).<tt> </tt>
A number of
<a href="#examples">
live examples
</a>
are provided below.<tt> </tt>
<br><br><br>
<h2>Server-side maps vs. client-side maps</h2>
There are two distinct types of clickable imagemaps:
<a href="http://hoohoo.ncsa.uiuc.edu/docs/tutorials/imagemapping.html">
server-side maps
</a>
and
<a href="http://www.netscape.com/assist/net_sites/html_extensions_3.html">
client-side maps
</a>
.
The two types are similar but have different syntaxes and are tied to an HTML web
page slightly differently.<tt> </tt>
Server-side maps have been around longer, but
may need to be specifically enabled in your web server by the administrator.<tt> </tt>
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.<tt> </tt>
<br><br><br>
<h2>Linking to your web page</h2>
<p>
In your web pages, you can use the following HTML construct
to associate a <b>server-side</b> map file with an image:
<pre>
<a href="mypic.map"> <img src="mypic.png" ismap > </a>
</pre>
<p>
Here's an HTML example that uses an embedded <b>client-side</b> map for an image:
<pre>
<img src="mypic.png" usemap="#map1">
<map name="map1">
... the map content that pl generates will go here ...
</map>
</pre>
<p>
Note: When ploticus generates a client-side map, it leaves off the opening <tt><map></tt>
and closing <tt></map></tt> tags. These tags will need to be added by the user.<tt> </tt>
<br><br><br>
<h2>Generating map files</h2>
To generate a server-side map file along with a PNG, GIF, or JPEG image file, use the <b>-map</b> option.<tt> </tt>
To generate a client-side map in a file, use the <b>-csmap</b> option.<tt> </tt>
The map file will have the same name as the graphic result file, except
that a <tt>.map</tt> suffix will be used.
If neither <b>-map</b> or <b>-csmap</b> are specified, then no map file will be generated.<tt> </tt>
Usage examples:
<dl>
<dt><dd><p>
<tt>pl -png -map -prefab pie ...</tt>
<br>
<tt>pl -png -map pie3.pl </tt>
<br>
<tt>pl -png -csmap pie3.pl </tt>
</dl>
<p>
The map file contains a list of URLs, one of which may be loaded when a
region in the graphic is clicked upon. Thus, you will
need to supply URL information (discussed below) in your script or
<a href="prefab_stdparms.html#clickmapurl">
prefab.<tt> </tt>
</a>
<p>
Note: If two generated mapped regions overlap, they are stacked in the order generated
(the last generated is on "top").<tt> </tt>
<br><br><br>
<h2>Troubleshooting</h2>
If the <b>-debug</b> command line option is used the mapped
regions will be displayed in bright green. If <b>-debug</b> is used in X11 mode, the regions
are displayed but no map file is generated.<tt> </tt>
<br><br><br>
<h2>Specifying URLs</h2>
Usually the programmer supplies URL template(s) or URLs within the script file
(eg. for pie graphs this is done within
<a href="pie.html">
proc pie
</a>
; for the plotting area it is done within
<a href="areadef.html">
proc areadef
</a>
).
<br><br><br>
<p>
<b>For pie graphs, bar graphs, and scatterplots</b>:
<dl>
<dt><dd><p>
Use <b>proc pie / bars / scatterplot</b> attribute <tt>clickmapurl</tt> to specify a URL template.<tt> </tt>
The template may contain
<a href="attributetypes.html#dfield">
data field references
</a>
prefaced by two at-signs (@@).<tt> </tt>
For example:
<pre>
clickmapurl: http://abc.com/mycgi?id=@@3
</pre>
would generate a URL for each
pie slice label, bar, scatterplot point, etc.,
using the value in data field 3 for each.<tt> </tt>
This example:
<pre>
clickmapurl: @@6
</pre>
would take the URL for each slice, bar, etc. from
data field 6.<tt> </tt>
URL templates work well for typical CGI invocations
where the CGI script name is constant and the parameters vary.<tt> </tt>
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.<tt> </tt>
<br><br><br>
</dl>
<p>
<b>For annotations:</b>
<dl>
<dt><dd><p>
Use <b>proc annotate</b> attribute <tt>clickmapurl</tt> to specify a URL explicitly.<tt> </tt>
For example:
<pre>
clickmapurl: http://abc.com/docs/aboutpets.html
</pre>
<br><br><br>
</dl>
<p>
<b>For legend entries:</b>
<dl>
<dt><dd><p>
Embed a URL into the <tt>legendlabel</tt> attribute (or if you are using
<a href="legendentry.html">
proc legendentry
</a>
the <tt>label</tt> attribute). Use this format: <tt>url:</tt><i>url</i><tt> </tt><i>label</i>
<br>
See this example:
<a href="../gallery/clickmap_leg.htm">
clickmap_leg
</a>
<br><br><br>
</dl>
<p>
<b>For the plotting area to be a single region:</b>
<dl>
<dt><dd><p>
Use <b>proc areadef</b> attribute <tt>clickmapurl</tt> to specify a URL.<tt> </tt>
XVAL and YVAL do not apply.<tt> </tt>
<br><br><br>
</dl>
<p>
<b>For grid regions within the plotting area:</b>
<dl>
<dt><dd><p>
Use <b>proc areadef</b> attribute <tt>clickmapurl</tt> to specify a URL template.<tt> </tt>
The template should contain special symbols <b>@@XVAL</b> and/or <b>@@YVAL</b>.<tt> </tt>
For example:
<pre>
clickmapurl: http://abc.com/mycgi?x=@@XVAL&y=@@YVAL
</pre>
Then use <b>proc axis</b> attribute <tt>clickmap</tt> for either the X axis, the Y axis,
or both.<tt> </tt>
</dl>
<dl><dt><dd>
<ul>
<li>
For a clickmap responding to different values in X, the above URL template should contain
<tt>@@XVAL</tt>, and set <b>proc xaxis</b> attribute <tt>clickmap: grid</tt>.<tt> </tt>
<li>
For a clickmap responding to different values in Y, the above URL template should contain
<tt>@@YVAL</tt>, and set <b>proc yaxis</b> attribute <tt>clickmap: grid</tt>.<tt> </tt>
<li>
For a clickmap responding to different values in X and Y, the above URL template should contain
both <tt>@@XVAL</tt> and <tt>@@YVAL</tt>, and set <b>proc xaxis</b> attribute <tt>clickmap: xygrid</tt>
and <b>proc yaxis</b> attribute <tt>clickmap: xygrid</tt>.<tt> </tt>
</ul>
</dl>
<dl>
<dt><dd><p>
The mapped regions will be centered around stubs.<tt> </tt>
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
<a href="scaleunits.html">
scale unit
</a>
but this can be controlled using <b>proc axis</b> <tt>clickmapvalformat</tt> attribute.<tt> </tt>
By default the regions will stop at the plotting area boundary,
but they can be extended (to encompass stubs for example) using <b>proc axis</b>
<tt>clickmapextent</tt> attribute.<tt> </tt>
<dt><dd><p>
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:
<pre>
#proc xaxis
stubs: inc <whatever>
clickmap: grid
axisline: no
tics: no
stubomit: *
<br><br><br>
</pre>
</dl>
<p>
<b>To set a default URL for the entire image:
</b><dl>
<dt><dd><p>
Use <b>proc page</b> attribute <tt>clickmapdefault</tt> to specify a default URL that will
be invoked if the mouse click is not in a defined region.
<br><br><br>
</dl>
<p>
<b>Notes:</b>
<p>
Embedded spaces and newlines that turn up within URLs will be converted to underscores.<tt> </tt>
<p>
Grid mapping may not be used with more than one plotting area per image.<tt> </tt>
<a name=examples></a>
<br><br><br>
<h2>Examples</h2>
Most of the following examples have been run with <b>-debug</b> to add the green
overlay showing where clickable regions are.
Try clicking on these images..<tt> </tt>
they are mapped to a live CGI program that will echo the passed parameters.<tt> </tt>
<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.<tt> </tt>
<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.<tt> </tt>
<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.<tt> </tt>
<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.<tt> </tt>
<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.<tt> </tt>
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.<tt> </tt>
<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.<tt> </tt>
Note that the mapped grid (Y) is influenced by <tt>stubslide</tt>.<tt> </tt>
<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.<tt> </tt>
<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 <b>proc axis</b> <tt>clickmapvalformat</tt>.<tt> </tt>
<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.<tt> </tt>
<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.<tt> </tt>
<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 <b>proc xaxis</b> <tt>clickmapextent</tt> attribute.<tt> </tt>
<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.<tt> </tt>
<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 <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 01, 2002.
</body>
</html>
|
