Image Maps in DocBook

Oxygen XML Editor includes support for image maps in DocBook documents through the use of the areaspec element. This feature provides an easy way to create hyperlinks in various parts of an image without having to divide the image into separate image files. The visual Author editing mode includes an Image Map Editor that helps you to easily create and configure image maps.

Figure: Image Map Editor in DocBook

Image Map Editor Interface in DocBook

The interface of the Image Map Editor consists of the following sections and actions:
Toolbar
New Rectangle
Use this button to draw a rectangular shape over an area in the image. You can drag any of the four points to adjust the size and shape of the rectangle.
Duplicate
Use this button to create a duplicate of the currently selected shape.
Delete
Use this button to delete the currently selected shape.
Undo
Use this button to undo the last action.
Redo
Use this button to redo the last action that was undone.
Show/Hide Numbers
Use this button to toggle between showing or hiding the numbers for the shapes.
Bring Shape to Front
Use this button to bring the currently selected shape forward to the top layer.
Bring Shape Forward
Use this button to bring the currently selected shape forward one layer.
Send Shape Backward
Use this button to send the currently selected shape back one layer.
Send Shape to Back
Use this button to send the currently selected shape back to the bottom layer.
Color Chooser
Use this drop-down menu to select a color scheme for the lines and numbers of the shapes.
Zoom Slider
Use this slider to zoom the image in or out in the main image pane.
Image Pane
This main image pane is where you work with shapes to add hyperlinks to multiple areas within an image. Use the mouse to move shapes around in the image to the desired area and drag the points on a selected shape to adjust its size and shape. It is easy to see which shape is selected in this image pane because the border of the selected shape changes from a solid line to a dotted line.
Area Properties
ID
The identifier for the selected area. This will become the value of the xml:id attribute for the particular area element.
Target
Allows you to choose the target resource that you want the selected area to be linked to. You can enter the path to the target in the text field but the easiest way to select a target is to use the Link drop-down menu to the right of the text field. You can choose between the following types of links: Cross Reference or Web Link. Both types open a dialog box that allows you to select the target resource and it is inserted as the value of an xlink:href attribute.
Description
You can enter an optional description for the selected area that will be displayed in the Image Map Details section in Author mode and as a tooltip message when the end user hovers over the hyperlink in the output.

How to Create an Image Map in DocBook

To create an image map on an existing image in a DocBook document, follow these steps:
  1. Right-click the image and select Image Map Editor.

    Result: This action will apply an image map to the current image and open the Image Map Editor dialog box.

  2. Add hyperlinks to the image by selecting the New Rectangle button.
  3. Move the shape to the desired area in the image and drag any of the points on the shape to adjust its size or form. You can use the other buttons on the toolbar to adjust its layer and color, or to perform other editing actions.
  4. With the shape selected, enter an ID and use one of the linking options in the Link drop-down menu to select a target resource (or enter its path in the Target text field).
  5. (Optional) Enter a Description for the selected area (shape).
  6. If you want to add more hyperlinks to the image, select New Rectangle button again and repeat the appropriate steps.
  7. When you are finished creating hyperlinks, click OK to process your changes.
Result: The image map is applied on the image and the appropriate elements and attributes are automatically added. In Author mode, the image map is now rendered over the image. If the image includes an alt element, its value will be displayed above the image. The following two buttons will also now be available at the top of the image in Author mode:
  • Image Map Editor - Click this button to open the Image Map Editor.
  • Image Map Details - Click this button to expand a section that displays the details of the image map.

How to Edit an Existing Image Map in DocBook

To edit an existing image map, right-click the image and select Image Map Editor (or click the Image Map Editor button above the image). This opens the Image Map Editor where you can make changes to the image map with a visual editor. You can also make changes to the XML structure of the image map in the Text editing mode.
Note: If you want to link a set of related area elements, you can use areaset elements. However, the layer buttons on the Image Map Editor toolbar (, , , ) will be disabled for areas inside an areaset element. Therefore, to change the layer of an areaset, you need to move it in Text mode where the layer order is sequential (the area or areaset that appears first is the top layer, and so on).

Overlapping Areas

If shapes overlap one another in the Image Map Editor, the one on the top layer takes precedence. The number shown inside each shape represent its layer (if the numbers are not displayed, click the Show/Hide Numbers button on the Image Map Editor toolbar). To change the layer order for a shape, use the layer buttons on the Image Map Editor toolbar (, , , ).

If you insert a shape and all of its coordinates are completely inside another shape, the Image Map Editor will display a warning to let you know that the shape is entirely covered by a bigger shape. Keep in mind that if a shape is completely inside another shape, its hyperlink will only be accessible if its layer is on top of the bigger shape.