Imagemaps

Imagemaps
	Chapter 18. Graphics

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.
Only the 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 graphicsize.extension and 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 mediaobjectco, imageobjectco, imagedata, areaspec and 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 must use a `mediaobjecto` element instead of a `mediaobject` element. It can be contained in a `figure` or `example` element in you want to add a title.
	The `imageobjectco` element contains a required `areaspec`, an `imageobject`, and an optional `calloutlist`. You do not have to use a `calloutlist`. The area links can be to any elements inside your documents.
	The `areaspec` element is the container for one or more `area` elements. Its `id` attribute becomes the map name in the HTML output.
	The `units` attribute is used to specify what kind of units the `coords` attribute contains. Only a `calspair` value and a nonstandard `imagemap` value are supported currently. You can put a `units` attribute on each `area` element, or put one `units` attribute on `areaspec` and it will be inherited by all the `area` elements contained by it.
	The `area` element specifies one area to become a link. Its `linkends` attribute should contain a reference to an `id` somewhere in the document. In this case, it is to a `callout` element below it. Although the DocBook `linkends` attribute allows more than one `id` value in it, the HTML imagemap can only take one reference.
	The `coords` attribute specifies the area size and location, using `calspair` units in this example. See the section “Using calspair coords” for details.
	You can specify an optional `id` attribute on each area, which you can link to from other locations. In most browsers, such links go to the whole graphic, not the specific area in it.
	If you use `callout` as the destination for an area link, then it must have an `arearefs` attribute that specifies an `id` for the callout to link back to. Most browsers follow such links to the overall image, not the specific area within the image. A `callout` is also numbered, so it might be useful to include the numbers in the image if you want them to correspond. Alternatively, you could use a bullet list item or ordinary paragraph with the `id` as the target of an imagemap link.
	The `id` on the `callout` element is the destination of the area link in this example.

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>

Using calspair coords

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.

Figure 18.1. DocBook calspair coordinates

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 graphicsize.extension and 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.

Using imagemap coords

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 otherunits attribute.

The DocBook stylesheets support setting units="other" and 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>
   ...

When 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.

Figure 18.2. HTML Imagemap Area Coordinates


SVG images		Chapter 19. Indexes