The <anchorkey> element allows an author to define a conref target that will be resolved dynamically when rendered for an end user of the content. This element is useful when doing an initial process of the DITA content prior to final rendering of the content; it allows specified keys to be preserved after that process, and conref relationships which use that key will not be resolved during that initial process.
When a keyref attribute is specified on an anchorkey element, it indicates that any conref relationships using that key will not be resolved. Applications that support run-time resolution of conref with keys will then be able to dynamically resolve this conref at display time.
There is no difference between specifying anchorkey within a map (in topicmeta) and specifying anchorkey within a topic. In both cases, processors are instructed to delay resolution of that key for the current set of information. However, the best practice is to only use anchorkey within a map. If it is specified in a topic, that topic will define a usage for the key for every user of that topic. This makes the topic less portable, because users that do not want to delay resolution of that specific key will not be able to include the topic in their information.
Many publishing systems for which DITA is used as a source format do not have a way to dynamically resolve content references; those systems will not see any benefit from this element. When DITA is used for those systems, behaviors related to this element should be ignored.
|map, bookmap, classifyMap, learningBookmap, learningMap||no content|
|map (base), map (technical content), bookmap, classifyMap, learningBookmap, learningMap||exportanchors|
In this example, a set of information contains multiple components. Some references to component A use keys rather than a direct reference, so that conref can be redirected to a different component when component A is not installed. The keys may be exported, in addition to the IDs, so that some references become bound to the actual component while other references may be redirected.
<map> <topicref keys="componentAconfig commonconfig" href="componentA/configA.dita#configA"> <topicmeta> <exportanchors> <anchorkey keyref="commonconfig"/> <anchorid id="step1"/> <anchorid id="step2"/> </exportanchors> </topicmeta> </topicref> </map>
The keys attributes declares two distinct keys that may be used to refer to this topic (componentAconfig and commonconfig). Only the second is preserved using anchorkey. A task topic from another component may reuse steps within this topic in a variety of ways.
<steps> <step conkeyref="componentAconfig/step1"><cmd/></step> <step conkeyref="componentAconfig/step1.5"><cmd/></step> <step conkeyref="commonconfig/step2"><cmd/></step> <step conkeyref="commonconfig/step2.5"><cmd/></step> <step><cmd>And that is the end of that</cmd> </steps>
This allows the information assembler to resolve references that must be to componentA while deferring references that can be fulfilled by alternative component content.
|Name||Description||Data Type||Default Value||Required?|
|keyref||Defines a key that, when possible, should be preserved in content generated from the DITA source material. Conref relationships that use this key should not be resolved when generating that material, so that conref may be resolved at run-time when an end user is reading the content.||NMTOKEN||#REQUIRED||Yes|
|univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups)||A set of related attributes, described in univ-atts attribute group|
|class, outputclass||Common attributes described in Other common DITA attributes|
|global-atts attribute group (xtrf, xtrc)||A set of related attributes, described in global-atts attribute group|
Return to main page.
OASIS DITA Version 1.2 -- OASIS Standard, 1 December 2010
Copyright © OASIS Open 2005, 2010. All Rights Reserved.