3.1.3.3.2 anchorid

The <anchorid> 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 causes specified IDs to be preserved after that process, and conref relationships that reuse the element will not be resolved during the initial process.

When the anchorid element is defined within a topic prolog, the specified IDs will be found within that topic. When an anchorid element is defined within a topicref element, the specified IDs will be found within the referenced topic (if the topicref points to a collection of topics, such as a reference that uses only a file name, the IDs will be found within the first or root topic).

The only difference between specifying an anchorid in the prolog and in topicmeta is that from the map it is possible to export the ID of the entire referenced topic. If <anchorid id="zero"/> is specified in the topicmeta, and the referenced topic has an id of "zero", this means that the anchorid is a reference to the entire topic. If the topic id is not "zero", then the anchorid is a reference to the element with id="zero" within that topic.

Along with the preservation of the element's ID, any conref attribute that references the element's ID will not be resolved during an initial process. In that case, the conref will be resolved during a later rendering process.

This description does not imply that IDs are not discarded when anchorid is not used; though this element requires that IDs be preserved in some manner, it is also common for IDs to be preserved when anchorid is not used. Thus the primary impact of the anchorid element is on conref resolution.

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.

Why not use topicid/elementid?

This element differs from normal DITA referencing syntax in that it may reference an element within a topic without using the topic's ID. There are two reasons for this. First, the anchorid element may only be defined in a situation that refers unambiguously to a single topic (in the prolog, or in the topicmeta for a reference to a topic). Second, it allows the anchorid to be combined with keyref values.

It is possible to combine an anchor id with a key in order to delay resolution of conref in the topic represented by that key (see the second set of examples below). This would not be possible if the anchorid element required both the topic id and the element id. That is, keyref allows a modifiable reference to a topic, so a map may instruct processors to delay conref for item step1 in the topic represented by the key "commonconfig". If the anchorid element required a topic id, the delayed conref would always be bound to that specific topic.

Contains

Note: These models represent only the default document types distributed by OASIS. Actual content models will differ with each new document type.
Doctype Content model
map, bookmap, classifyMap, learningBookmap, learningMap no content

Contained by

Doctype Content model
map (base), map (technical content), bookmap, classifyMap, learningBookmap, learningMap exportanchors

Inheritance

+ topic/keyword delay-d/anchorid

Example

Figure 1. Use case 1: Runtime resolution of conref to an id, determined by original author
  1. Author 1 creates topics for information component A, which is a common component used by many products. The configuration task for component A is often reused in whole or in part, so the author assigns ids to each of the steps in the procedure and exports them. 
    <task id="configA">
  <title>ABC<title>
  <shortdesc>...</shortdesc>
  <prolog><metadata>
    <exportanchors>
      <anchorid id="step1"/>
      <anchorid id="step2"/>
      <anchorid id="step3"/>
    </exportanchors>
  </metadata></prolog>
  <taskbody>
    <steps>
      <step id="step1"><cmd>Do this</cmd></step>
      <step id="step2"><cmd>Do the other</cmd></step>
      <step id="step3"><cmd>And then finish</cmd></step>
    </steps>
  </taskbody>
</task>
  2. Author 2 is working on information component B, which has information component A as a prerequisite.
  3. Author 2 creates a configuration task that reuses two steps from the configuration task in information component A.
    <task id="configB">
  <title>..</title>
  <shortdesc>..</shortdesc>
  <taskbody>
    <steps>
      <step><cmd>Do the very first thing</cmd></step>
      <step conref="componentA/configA.dita#configA/step1"><cmd/></step>
      <step><cmd>Do the middle thing</cmd></step>
      <step conref="componentA/configA.dita#configA/step2"><cmd/></step>
    </steps>
  </taskbody>
</task>
  4. Author 2 builds the content for component B into a deliverable format that supports dynamic content resolution. As with traditional conref, the source for component A must be available during this process. Because the ids in configA are exported, the build process knows to preserve the reuse relationship rather than resolve it - so the conref to the steps becomes an equivalent reuse artifact in that deliverable format. This way the relationship to component A can be resolved at runtime, and pick up the user's version of component A, which may be more up-to-date than the one used by Author 2 when component B was built.
Figure 2. Use case 2: Runtime resolution to an id exported by the information builder
  1. Author 1 is creating content that will be packaged into multiple deliverable components. In one of those components, component A, the ids should be exported for runtime reuse by other components. In other components, the ids should not be exported because all reuse is local (for example, the output is a single infocenter, or a helpset that has only one component).
  2. When author 1 builds component A, the author uses a map that exports the ids, rather than exporting the ids from the topic prolog. 
    <map>
  <topicref href="componentA/configA.dita">
    <topicmeta>
      <exportanchors>
        <anchorid id="step1"/>
        <anchorid id="step2"/>
        <anchorid id="step3"/>
      </exportanchors>
    </topicmeta>
  </topicref>
</map>
  3. The rest of the use case is the same as previous - the conref is passed on to the runtime/display format to deal with, rather than being resolved during native DITA processing.
Figure 3. Delaying resolution for a topic

The ID on an <anchorid> element is first compared with the topic's id, and then with elements inside that topic. This results in the following situation.

<map>
  <topicref href="componentA/this.dita">
    <topicmeta>
      <exportanchors>
        <anchorid id="this"/>
        <anchorid id="that"/>
      </exportanchors>
    </topicmeta>
  </topicref>
</map>

<topic id="this">
  <title>This and that</title>
  <shortdesc>Oh, you know, this and that.</shortdesc>
  <body>
    <fig id="that"><p>more of that</p></fig>
  </body>
</topic>
  • The first ID to be exported is "this", which matches the topic id, so resolution of conref values that target the topic should be delayed.
  • The second value is "that", which matches a figure within the topic, so resolution of conref values that target the figure should be delayed.
  • Note that if the "this" is also used within the topic (which is legal from a DITA perspective), it will not be possible to export that id, because processors will match on the topic's id first.

Example

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.

Note: This example demonstrates why the anchorid element cannot reference an element with the usual topicid/elementid format. If the two anchorid elements in the example had been set to config/step1 and config/step2, then they would only ever apply in a topic with id="config". It would not be possible to redirect the key to another topic, but still preserve conref behaviors as desired.
Note: Although it is not specifically called out in this example, it is possible to delay conref resolution for an entire topic using the key. If conkeyref on a task topic element is set to "componentAconfig", which is not delayed, the conref will be evaluated as usual. However, if conkeyref on the task is set to "commonconfig", which is delayed, resolution of conref on that element should be delayed by a processor.

Attributes

Name Description Data Type Default Value Required?
id Indicates an ID within the a specific topic that will be preserved during processing. Any conref values referencing the indicated ID will not be resolved; when possible, the original relationship should be preserved in any processed document. Note that this element creates an exception to the general rules that IDs may only be used once within a single topic or within a map; this is because the ID is actually a pointer to another target, rather than being a target itself. CDATA #REQUIRED Yes
keyref Keyref provides a redirectable reference based on a key defined within a map. See The keyref attribute for information on using this attribute. CDATA #IMPLIED No
conref-atts attribute group (conref, conrefend, conaction, conkeyref) A set of related attributes; includes all of the attributes described in id-atts attribute group except for the id attribute.      
select-atts attribute group (props, base, platform, product, audience, otherprops, importance, rev, status) A set of related attributes, described in select-atts attribute group      
localization-atts attribute group (translate, xml:lang, dir) A set of related attributes, described in localization-atts attribute group.      
global-atts attribute group (xtrf, xtrc) A set of related attributes, described in global-atts attribute group      
class, outputclass Common attributes described in Other common DITA attributes      
Parent topic: 3.1.3.3 Delayed conref resolution elements
Previous topic: 3.1.3.3.1 exportanchors
Next topic: 3.1.3.3.3 anchorkey

Return to main page.

DITA v1.2 CS 01
Copyright © OASIS Open 2005, 2010. All Rights Reserved.