Using keys to address DITA elements

For topic references, image references, and navigation link relationships (<link>, <xref>, and elements that take the @keyref but not the @href attribute), resources can be addressed by key using the @keyref attribute. For content reference relationships, resources can be addressed by key using the @conkeyref attribute.

Syntax

For references to topics, maps, and non-DITA resources, the value of the @keyref attribute is simply a key name: keyref="topic-key".

For references to non-topic elements within topics and non-topicref elements within maps, the value of the @keyref attribute is a key name, a solidus ("/"), and the ID of the target element: keyref="topic-key/some-element-id".

If both @keyref and @href attributes are specified on an element, the @href value must be used as a fall-back address when the key name is undefined, and should be used as a fall-back address when the key name is defined but the key reference cannot be resolved to a resource. If both @conkeyref and @conref attributes are specified on an element, the @conref value must be used as a fall-back address when the key name is undefined, and should be used as a fall-back address when the key name is defined but the key reference cannot be resolved to a resource.

Example

For example, consider this topic in the document "file.dita":

<topic id="topicid">
 <title>Example referenced topic</title>
 <body>
  <p id="para-01">Some content.</p>
 </body>
</topic>

and this key definition:

<map>
  <topicref keys="myexample"
    href="file.dita"
  />
</map>

A keyref of the form "myexample/para-01 resolves to the <p> element in the topic. The key reference would be equivalent, in the context of this map, to the URI reference file.dita#topicid/para-01.

A key reference to a topicref element where the linking element specifies a format value of "ditamap" addresses the topicref element itself as though the topicref element had been addressed by ID. In particular, a topicref with a key reference to another topicref and a format value of "ditamap" is a use of the map branch rooted at the referenced topicref.

2.1.3.4.3.2 Using keys to address DITA elements

Syntax

Example