Key references

Last Updated : Sep 09, 2015 |
Prolog information
Metadata
Keywords:
The key-reference mechanism in DITA provides a layer of abstraction so that referenced content strings can be defined externally at the DITA map level instead of locally in each topic. Key references (keyrefs) are conceptually similar to content references (conrefs) in that they’re references that point to content that resides somewhere else. There are many possible implementations of key references in DITA. Currently in GIS we’re using keyrefs to define variables.
When you use DITA topics in different publications, there might be names of objects that should have different values, depending on the context. With keyrefs, you name the variables using the <keydef> element. For example, you might have a keydef for the name of a server that changes depending on the implementation When you insert a <keydef> element in a topic, it has no defined value—it’s just a placeholder reference. You define the <keydef> value in special key DITA Maps. Each key map can contain different values for the <keydef> elements that you’ve defined. Then, depending on which key map you include in your bookmap, the value of the <keydef> is applied during production. You can change the value of the variable by using a different key maps in different bookmaps. Or you can include multiple key maps in single bookmap and apply conditions to them. You can then use the bookmap in different publications and select different conditions to achieve different values in the outputs.

Using existing elements as keyrefs

You can also use existing elements as variables using the keyref mechanism. This implementation has an additional level of indirection, but it allows us to use elements already set up for reuse as keyrefs. You can think of keyrefs defined directly in key maps as direct keyrefs and keyrefs that reuse elements as indirect keyrefs.
Important:
Because of the way that keys are referenced in the topics, each variable you want to use must always be specified directly in the maps or must always be referenced indirectly through reuse. You cannot define a key reference that’s defined directly in some contexts and indirectly in other contexts.

Key references vs. conditions

Keyrefs can be used in some cases in ways that are similar to conditions. In the case of conditions, the possible values reside in the topics, with conditions applied, and the conditions used in the publication determine the value that appears in the output. With keyrefs, you include a single placeholder (keydef) and the possible values are defined externally in key maps. Whether conditions or keyrefs are the right approach really depends on the specific situation and what you need to implement. If you think your project has a use for keyrefs, contact Sue.