exportanchors
The exportanchors element may be used within a topic prolog, in which case the defined IDs apply to IDs within that topic (excluding sub-topics). Alternatively it may be defined in the topicmeta in a map. In the second case the IDs apply to the single topic referenced by the current topicref element. If the topicref points to a file without referencing a specific topic, it is treated as a reference to the first or root topic. In order to define anchor ids for a topic that is not the first or root topic, a topicref must directly reference the desired sub-topic.
Note
One possible way to use this is with a system that renders DITA dynamically. A user may process information locally in a way that resolves conref for all static information, while delaying resolution for information that is subject to change. The exportanchors element is used to define conref values that are delayed.
Another potential use is when DITA is used as the source format for a publishing system that is able to render information dynamically. In this case some conref values may be resolved, while leaving pre-selected values to be resolved live in that publishing system.
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.
Contains
Note
| Doctype | Content model |
|---|---|
| map, bookmap, classifyMap, learningBookmap, learningMap | (anchorid or anchorkey) (any number) |
Contained by
| Doctype | Content model |
|---|---|
| map (base), map (technical content), classifyMap, learningMap | metadata, topicmeta |
| bookmap, learningBookmap | metadata, topicmeta, bookmeta |
Inheritance
+ topic/keywords delay-d/exportanchors
Example
Use case 1: Runtime resolution of conref to an id, determined by original author
- 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> - Author 2 is working on information component B, which has information component A as a prerequisite.
- 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> - 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.
Use case 2: Runtime resolution to an id exported by the information builder
- 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).
- 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> - 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.
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>
- The componentAconfig key is not preserved, so the first step becomes
<step conref="componentA/configA.dita#configA/step1"><cmd/></step>. At that point the anchorid element instructs the step1 ID to be preserved; for runtime applications which support it, this relationship will be preserved in the processed DITA output. - The second step with the same key becomes
<step conref="componentA/configA.dita#configA/step1.5"><cmd/></step>. However, conref relationships to step1.5 are not preserved, so this conref should be resolved into static content. - For step three, the map instructs that both the key commonconfig and the ID step2 should be preserved in any content generated for this DITA topic. For formats that support runtime resolution through keys, a process must convert the conkeyref value into an equivalent value for that format.
- Although resolution for the key used in step four is delayed,
the specific element that is referenced should not be delayed. Thus
the fourth step becomes
<step conref="componentA/configA.dita#configA/step2.5"><cmd/></step>. This value is then processed as an ordinary conref value.
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
Note
Attributes
| Name | Description | Data Type | Default Value | Required? |
|---|---|---|---|---|
| univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups) | A set of related attributes, described in univ-atts attribute group | |||
| global-atts attribute group (xtrf, xtrc) | A set of related attributes, described in global-atts attribute group | |||
| class | A common attribute described in Other common DITA attributes |