17.3. Creating and using an annotated variant of image file

Normally, the “hot areas” drawn using the image map editor are not visible to the user. For example, if you convert a DITA imagemap to XHTML, the Web browser will simply display the image as is. The user will understand that the image has “hot areas” only when she/he'll hover the mouse pointer above these “hot areas”.

However, in some cases, making the “hot areas” visible and/or giving them numbers so they can be referred to by number may be useful. This can be done by clicking the "Create and use an annotated variant of image file" button and checking the "Highlight Areas" and/or "Number Areas" checkboxes.

Figure 9.33. The popup menu displayed by clicking the "Create and use an annotated variant of image file" toolbar button
The popup menu displayed by clicking the "Create and use an annotated variant of image file" toolbar button

The other entries of the above menu let the user customize the appearance of the visual marks she/he has chosen to add to the image. In the following figure, the user has chosen yellow on purple numbers using a 9pt font size and thick, dashed, purple highlights.

Figure 9.34. Example of annotated image preceding an XHTML map
Example of annotated image preceding an XHTML map

Note that these visual marks are not rendered by the image map editor itself, as this would make drawing new shapes more difficult. Instead, it works as follows: after checking the "Highlight Areas" and/or "Number Areas" checkboxes and clicking OK, an SVG image embedding the original image and adding the chosen visual marks above this image is automatically generated.

For example, if a DITA imagemap contains <image href="images/imagemapworld.jpg">, this facility automatically generates SVG file "imagemapworld.jpg.marked.svg" and replaces the value of the href attribute by images/imagemapworld.jpg.marked.svg.

Note that the format of the image to be annotated must be GIF, PNG, JPEG or SVG, otherwise the "Create and use an annotated variant of image file" toolbar button is disabled (grayed).

[Important]Image annotations are created only for areas having link targets

“Dead areas”, that is, areas having no link targets, are ignored by this facility.

Therefore, if you use tool bar button "Add image" in XMLmind XML Editor - DocBook Support and select "mediaobject(calloutlist)" to add a mediaobject element containing imageobjectco element to your document, you must proceed as follows:

  1. Specify an image file, for example, by right-clicking the image placeholder and then selecting "Set Image".

  2. Right-click anywhere inside the newly inserted imageobjectco element and select "Edit Image Map".

  3. Use the image map editor to add “hot areas” to your image. Do not bother setting the links of any of these hot areas because there is a way to do this automatically.

  4. Add one callout per hot area to the calloutlist. The number and order of the callouts must match the number and order of the hot areas because this is how the correspondence between a hot area and a callout is established. Do not bother setting the links of any of these callouts because there is a way to do this automatically.

  5. Use DocBookLink callouts in XMLmind XML Editor - DocBook Support to link the hot areas to the corresponding callout elements (and the other way round of course).

  6. Now that the DocBookLink callouts command has automatically added link targets to all areas, you may use the "Create and use an annotated variant of image file" facility.