An imagemap displays an image in an HTML browser that has active areas that a user can click on to jump to another location. The DocBook HTML stylesheets have some support for creating client-side imagemaps using the
mediaobjectco element. But there are some limitations in how imagemaps are supported in the HTML stylesheets.
A link from a DocBook
area element must be to a destination in the current document, not to an external URL. That is because the
linkends attribute in the DocBook
area element is of attribute type
IDREFS, so it must point to an
id attribute in the current document.
Only bitmap images are supported, not vector art such as SVG.
The image cannot be resized in the output. Any scaling of the image breaks the conversion of areas in the current implementation.
Only rectangular areas are supported.
calspair type of coordinates or an application-specific set of units named
imagemap are supported in DocBook
area elements. These two options are described in the section “Using calspair coords” and the section “Using imagemap coords”.
If you are using
calspair type of units, the stylesheet parameters
use.extensions must both be set to 1. This means you must be using either Saxon or Xalan and have the appropriate DocBook Java extensions file in your processor's CLASSPATH. See the section “DocBook Saxon and Xalan extensions”.
If you can live with these limitations, imagemaps can be quite useful for certain kinds of documentation efforts. Because the area links must land inside the current document, they are best used for providing dynamic explanation of a diagram., or a graphical map to the rest of the documentation. Unfortunately, none of the area links will be active in a PDF version if you produce that also.
A DocBook imagemap is created using the DocBook elements
area. An optional
calloutlist can be used for the link destinations. The following example shows the DocBook elements to produce an imagemap with one area specified.
Example 18.3. DocBook imagemap using calspair units
<mediaobjectco> <imageobjectco> <areaspec id="map1" units="calspair"> <area linkends="callout1" coords="1000,5000 6000,8000" id="area1"/> </areaspec> <imageobject> <imagedata fileref="tablerules.png" /> </imageobject> <calloutlist> <callout arearefs="area1" id="callout1"> <para>My only callout</para> </callout> </calloutlist> </imageobjectco> </mediaobjectco>
You can specify an optional
If you use
The following shows how the DocBook XHTML stylesheet renders this imagemap. The various id and coordinate values are shown in bold.
<div class="mediaobjectco"> <img border="0" usemap="#map1" src="tablerules.png" alt="imagemap"/> <map name="map1"> <area shape="rect" href="#callout1" coords="102,154,614,384"/> </map> <div class="calloutlist"> <table border="0" summary="Callout list"> <tr> <td width="5%" valign="top" align="left"> <a id="callout1"/> <img src="images/callouts/1.png" alt="1" border="0"/> </td> <td valign="top" align="left"> <p>My only callout</p> </td> </tr> </table> </div> </div>
The hardest part of creating an imagemap in DocBook using
calspair units is figuring out how to express the HTML coordinates in the CALS semantics. Here is the description of
calspair from DocBook: The Definitive Guide.
The format of the coordinates is
"x1,y1 x2,y2". This identifies a rectangle with the lower-left corner at (x1,y1) and the upper-right corner at (x2,y2). The X and Y coordinates are integers in the range 0 to 10000; they express a percentage of the total distance from 0.00 to 100.00%. The lower-left corner is (0,0).
You measure the area in hundredths of percentage of whatever is the size of the graphic, measured from the lower left corner. Note the space between the two pairs of numbers. In Figure 18.1, “DocBook calspair coordinates”, the calspair values are shown as ordinary percentages on the diagram.
Since calspair are proportional units, the stylesheet has to determine what the intrinsic pixel size of the whole image is so it can compute the HTML imagemap area, which must be in pixels. Getting the intrinsic image size requires a stylesheet extension. This means you must use either Saxon or Xalan as your XSLT processor, and you must have the appropriate DocBook Java extensions
.jar file in your processor's CLASSPATH (see the section “DocBook Saxon and Xalan extensions” for more information). The stylesheet parameters
use.extensions must both be set to 1. When these conditions are met, the stylesheet computes the equivalent HTML imagemap pixel units as shown in Figure 18.2, “HTML Imagemap Area Coordinates”.
Norman Walsh has written an article called Image callouts that describes a method and provides a Perl script for creating callouts on images using calspair coordinates without having to perform hand calculations.
If you are using
mediaobjectco only to create HTML imagemaps, then the stylesheets provide an easier way to specify the area coordinates. The DocBook DTD enumerates the types of units that can be used in the
units attribute, of which only
calspair is supported by the stylesheet. However, the enumeration also permits specifying
units="other", and then specifying the type of units in the
The DocBook stylesheets support setting
otherunits="imagemap", and then entering the imagemap pixel ranges directly in the
coords attribute of a DocBook
area element. An imagemap
coords value is four numbers in the form
x1,y1,x2,y2 (all comma separated). These specify the positions of the upper-left corner (x1,y1) and the lower-right corner (x2,y2) of the area, measured in pixels. The upper-left corner of the entire image is (0,0). The following is an example.
Example 18.4. DocBook imagemap using “imagemap” units
<mediaobjectco> <imageobjectco> <areaspec id="map1"> <area linkends="callout1" units="other" otherunits="imagemap" coords="102,154,614,384" id="area1"/> </areaspec> <imageobject> <imagedata fileref="tablerules.png" /> </imageobject> ...
otherunits="imagemap", the stylesheet just copies the value of the input
coords attribute to the output
coords attribute. The following figure shows how the same output as the previous
calspair example can be achieved by entering the pixel values directly.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises