Inserting a keyword or external link from keys defined in the map

You can insert a key into your content from the keys defined in the map.

The Insert Variable dialog box obtains its values from the keys defined in the map open in the DITA Map view. Keys can be added to maps in several ways such as defining them directly in the ditamap or including submaps containing keys. If a key has the potential for multiple values as a result of being defined in different places, the key definition highest in the map hierarchy prevails. This means if you have a map containing nested submaps and the submaps contain a key defined with the same name but with different values, then the key value defined in the topmost map in the hierarchy is the value used in the topics.

For example, Map A contains Map B and Map B contains Map C. A key named "product" is defined in each map, but their values are not the same. In this case, the value defined for the key in Map A is used. If the "product" key was defined in Map B and Map C but not in Map A, then the value in Map B is used since it is higher in the map hierarchy than Map C.

When you click Insert variable from map, it inserts a keyword (<keyword keyref="[value]"/>) at the location where you have placed your cursor. When you click Insert external link from map, it inserts a link (<xref keyref="[value]"/>).

Restriction: Glossary keys are not available using this dialog box.

To insert the variable or link:

  1. Place your cursor at the location where you want to insert the key.
  2. Do one of the following depending on the type of key you want to insert:
    Option Description
    For oXygen XML Editor
    • To insert a keyword, click the Insert Variable from map button from the main toolbar.
    • To insert a link, click the Insert external link from map button from the main toolbar.
    For XMetaL XML Editor
    • To insert a keyword, right-click and click Insert variable from map.
    • To insert a link, right-click and click Insert external link from map.
  3. In the Variable column, click the variable that you want to insert. To search for a variable, type a relevant string of characters in the Filter results field.
    Note: The variables are organized in the Insert Variable dialog box by the map in which they are defined. If a variable is greyed out, it means it is defined in another map higher in the map hierarchy.
  4. Click OK.