DITA uses keys to insert content that may have different values in various circumstances. Keys provide a way to reference something indirectly. This can make it easier to manage and to reuse content in a number of ways.
You can think of keys like renting a post office box. Instead of the mail going directly from the sender to your house, it now goes to the post office box. You then go to the post office box and bring the mail back to your house. If you move to a new house, your mail still gets to you because it comes to the same post office box. You do not have to send change of address cards to all the people who send you mail. Your mailbox address is the key that makes sure your mail always reaches you, even if you move.
Similarly, if you use keys in your content to reference other content, you do not have to update the source content in order to change the value of the key or what it points to. You just change the definition of the key.
Keys are thus a very general mechanism. DITA uses keys for referencing different kinds of content for various purposes.
Using Keys for Values
You can use keys to represent values that may vary in different outputs. For instance, you may have several products that share a common feature. When you want to describe that feature, you need a way to insert the name of the product, even though that name is different depending on which product the feature description is being used for.
Assigning Keys to Topics
You can assign a key to a topic and use that key to reference that topic for various purposes, such as reuse or linking. As always, keys are defined in maps, so the key definition is done using the keys attribute of the topicref element:
<topicref href="quick-heat.dita" keys="feature.quick-heat"/>You can also assign keys to a topic (and insert the topicref element in its DITA map) by using the Keys tab in the Edit Properties dialog box. In the DITA Maps Manager, invoke the contextual menu on the topic for which you want to assign a key and select
Edit
Properties. Go to the Keys tab and enter the name of the
key in the Define keys field.- You can create a link to it using <xref keyref="feature.quick-heat"/>. This allows you to change the target of the link by changing the topic that is pointed to by the key (for example, by profiling).
- You can use it in a map to create a reference to a topic by key: <topicref keyref="feature.quick-heat". This allows you to change which topic is inserted in the map by the build, by changing the topic that is pointed to by the key.
- You can use it to insert a content reference. In this case, the content reference uses the key to locate the topic to pull content from. It uses a conkeyref attribute: <procedure conkeyref="feature.quick-heat/preheat-procedure"/>. In this example, feature.quick-heat is the key, and preheat-procedure is the id of a procedure within the topic for that key. Using this mechanism, you could have multiple versions of the preheat procedure in various topics and control which one is inserted by changing the topic that is pointed to by the key.
Assigning Keys to Graphics
You can assign a key to an image (using a map to point to the image file) and insert the image using the key.