Inserting and Defining Keys in DITA Maps

DITA uses keys to insert content that may have different values in various circumstances. Keys provide the means for indirect referencing in DITA. This can make it easier to manage and to reuse content. In DITA, keys are defined in maps and can then be reused and referenced throughout the whole structure of the map.

The following example is a DITA map that defines various values for the product key:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <!-- product name -->
  <keydef keys="product" product="basic">
    <topicmeta>
      <keywords>
        <keyword>Basic Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="product" product="pro">
    <topicmeta>
      <keywords>
        <keyword>Professional Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="product" product="enterprise">
    <topicmeta>
      <keywords>
        <keyword>Enterprise Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
</map>

Note: The profiling of the names is now contained in the map, where it only has to occur once to reuse throughout the whole map structure.

Key Definition with a Keyword

To insert a key definition with a keyword in a DITA map, follow these steps:

Open the DITA map in the DITA Maps Manager.
Invoke the contextual menu and select Key Definition from the Append Child or Insert After submenu (depending on where you want to insert the key definition in the DITA map). This opens an Insert Key Definition dialog box.
Go to the Keys tab and enter the name of the key in the Define keys field.
Go to the Metadata tab and click Add keyword. In the editing window enter the key value inside the keyword element.
Note: You can profile the key by using the Profiling tab and other attributes can also be defined in the Attributes tab.
Once you are done configuring the key definition, click Insert and close.

Alternatively, there is a simplified method that can be used if you simply want to define a key with a value inside a keyword, without configuring any profiling or other attributes. To use the simplified method, follow these steps:

Open the DITA map in the DITA Maps Manager.
Invoke the contextual menu and select Key Definition with Keyword from the Append Child or Insert After submenu (depending on where you want to insert the key definition in the DITA map). This opens a simplified Insert Key Definition dialog box.
Enter the name of the key in the Key field and its value in the Keyword field.
Click Insert and close to finalize the operation.

Key Definition with a Target

To insert a targeted key definition (for example, to target a resource such as an image or topic) in a DITA map, follow these steps:

Open the DITA map in the DITA Maps Manager.
Invoke the contextual menu and select Key Definition from the Append Child or Insert After submenu (depending on where you want to insert the key definition in the DITA map). This opens an Insert Key Definition dialog box.
Go to the Keys tab and enter the name of the key in the Define keys field.
Go to the Target tab and select a target resource (such as an image or topic).
Note: You can profile the key by using the Profiling tab and other attributes can also be defined in the Attributes tab.
Once you are done configuring the targeted key definition, click Insert and close.