Create a key definition

You can define a variable in a map as a key and then insert that key into any number of topics within the map.

Keys are useful for managing content consistency and for efficiency. For example, you can use keys to define names for products or product features. If names change over time, you don't need to edit all the topics that mention the product or feature. You only need to edit the key in the map that defines that product or feature name. Further, if you have two maps where the same key defines a name differently, topics with that key automatically update with the correct product or feature name for the related map.

Note: You must check in a map before any new key definitions go into effect.

The two most typical methods to define and add keys to your content are to:

  • Define keys in a map, and then add them to the topics in that map.
  • Define keys in a submap. From then on, you can reuse the submap by adding it to other maps with topics that require the keys you defined.
Note: If multiple definitions of a key exist within a map, the first definition takes precedence over any subsequent definitions, unless you set a specific scope for the keys that alters this default.

To create a key definition:

  1. In Structure view for Map Editor click Edit.
  2. Select the location in the map where you want to add the key, and then click .
    A pop-up menu results.
  3. From the pop-up menu, select New Element, and then choose Same Level or Sub Level, based on whether you need to create the key as a sibling or child of the item you selected.
    The New Element dialog opens.
  4. In the New Element dialog, click the Element dropdown menu and select <keydef>.
  5. In the Keyname field, enter the name of the key.
  6. For the Value, choose one of the following options:
    • Keyword provides you with an addition to the keys map and requires you to enter a value that you will use as a reference for that key.
    • Object Reference supports insertion of a reference to an image, topic, or map resource, but requires you to enter its scope as defined by DITA: local, peer, or external.
    • New Topic Reference supports creation of targeted keys, based on the topic conditions you set.
    • Web Link provides support for referencing live website links
  7. Click Insert.

The map now contains the <keydef> element with the values you defined.

Once you check in the map, you can insert the key you defined into a topic.