Working with Images in DITA Topics

There are several ways to add images to a DITA topic, depending on if you want to create a figure element (with a title and caption), just insert an image inline, or if you want to use multiple versions of a graphic depending on the situation. For instance, you might want to use a specific image for each different product version or output media.

Adding an Image Inline with the Insert Image Dialog Box

Use the following procedure to add an image inline:

  1. Place the cursor in the position you want the graphic to be inserted.

  2. Select the Insert Image action. The Insert Image dialog box appears.

    Figure 1. Insert Image Dialog Box

  3. Configure the options in this dialog box and click Insert.

    The Insert Image dialog box includes the following options and features for inserting images into a DITA document:
    Location
    Use this option to specify a URL for the image as the value of an @href attribute inside the <image> element. You can type the URL of the image you want to insert or use browsing actions in the Browse drop-down menu (there is also a history drop-down).
    Key
    Use this option to insert the selected key as the value of a @keyref attribute inside the <image> element. All keys that are presented in the dialog box are gathered from the root map of the current DITA map. You can use the Choose Key Reference button to open the Choose Key dialog box that presents the list of keys available in the selected root map.
    Note: If your defined keys are not listed in this dialog box, it is most likely trying to gather keys from the wrong root map. You can change the root map by using the Change Root Map link in the Choose Key dialog box or change it in the Context option in the toolbar of the DITA Maps Manager.
    Figure title
    Use this text box to insert a <title> and <image> element inside a <fig>.
    Alternate text
    Use this text box to insert an <alt> element inside the <image>.
    Size
    Use this section to configure the Width and Height of the image, or Scale the image. Specifying a value in these options inserts a @width, @height, and @scale attribute, respectively.
    Layout
    Use the options in this section to insert @placement and @align attributes into the <image> element.
    Preview
    The Preview box shows a thumbnail of the selected image so that you can see a preview of the image before clicking Insert.

Adding an Image Inline with Drag/Drop (or Copy/Paste) Actions

You can drag images from your system explorer or the Project Explorer view and drop them into a DITA document (or copy and paste). This will insert the path of the image file as the value of the @href attribute in a DITA <image> element:
<image href="../images/image_file.png"/>
Tip: To replace an image, just drag and drop a new image over the existing one. Oxygen XML Author Eclipse plugin will automatically update the reference to the new image.

Adding an Image in a Figure Element

To add an image in a figure:

  1. Add a <fig> element to your document at the appropriate place.
  2. Add a <title> and/or <desc> element to <fig>, according to your needs.
  3. Add an <image> element to the <fig> element.
Note: The <fig> element has a number of other child elements that may be appropriate to your content. See the DITA documentation for complete information about <fig>.
Note: The order that the content of the <image>, <title>, and <desc> elements will appear in the output is determined by the output transformation. If you want to change how they appear, you may have to modify the output transformation, rather than your source content.

Floating Images in DITA Topics for PDF or XHTML Output

Oxygen XML Author Eclipse plugin provides the possibility of floating an image to the left or right of blocks of content in DITA topics, for both PDF and XHTML output.

To float an image, you simply need to set the @outputclass attribute on the <image> element. The possible values are:
  • float-left
  • float-right
For example, the following DITA structure will present the image to the right of the paragraph content in the output:
<p><image href="../../images/Lilac.jpg" scale="45" outputclass="float-right"/>
  <b>Lilac</b> (<b>Syringa</b>) is a genus of about 20–25 species of flowering plants
  in the olive family (<b>Oleaceae</b>), native to Europe and Asia.
</p>
Figure 2. Image Floated to the Right

Searching for References to Images

You can search for all references to an image by selecting Search References from the contextual menu. The result depends on how the image is defined, as follows:
  • If the action is invoked on an <image> element that contains an @href attribute but does not include an @id attribute, all direct references to the image are reported. If the <image> element does have an @id attribute, all links to the specified ID are also reported.
  • If the action is invoked on an <image> element that contains a @keyref attribute but does not include an @id attribute, all direct references to the image are reported along with all instances where the key is used. If the <image> element does have an @id attribute, all links to the specified ID are also reported.
Parent topic: Working with DITA Topics
Previous topic: Changing the Look of DITA Documents in Author Mode Using the Styles Menu
Next topic: Adding Video, Audio, and Embedded HTML Resources in DITA Topics
Related information