A DITA key allows you to create a placeholder for a file path or a short piece of text. You create the key name and definition (the text to use in place of the key) in a DITA map;. You refer to a key by specifying the key name in a keyref attribute. The keyref attributes are resolved when topics and maps are transformed into an output format.
The advantage of using a key is that you define the key in one place (in the map), then refer to that key by name throughout all your topics. If the file path or text changes, you only need to change the definition and the new definition is reflected everywhere that the keyref attribute is used.
Keys make it easy to create reusable topics. Because key definitions can be different for each map, a reusable topic that uses keys can contain different file paths or strings, depending on which map it is used in.
- The key product_name contains the name of a product
- The key product_image contains the path to a picture of the product
In the map for Product A, product_name could be defined as “Product A” and product_image as “images/ProductA.png”.
In the map for Product B, product_name could be defined as “Product B” and product_image as “images/ProductB.png”.
When your topic is used in the map for Product A, the product name “Product A” is used and the product image shows the correct product. When your topic is used in the map for Product B, the correct product name and image are shown for that product.
You define keys in a DITA map with the <keydef> element, which is a specialization of the <topicref> element.
There are some differences between keys used for paths and keys used for text strings. There are differences in how you define the keys and how you use them. These two uses are described in the next two topics.
Note: This description of keys does not address scoped keys, which were introduced in DITA 1.3. The concept of scoped keys will be addressed in a future LearningDITA course.
Note: There is a third use for keys: they can be used to specify a path to conref content. These “conkeyrefs” are addressed in the next lesson (“Advanced conrefs”).