The topicref element identifies a topic (such as a concept, task, or reference) or other resource. A topicref can contain other topicref elements, allowing you to express navigation or table-of-contents hierarchies, as well as implying relationships between a containing (parent) topicref and its children. You can set the collection type of a parent topicref to determine how its children are related to each other. You can also express relationships among topicref elements by using group and table structures (such as topicgroup and reltable). Relationships are expressed as links in the output; by default, each participant in a relationship has links to the other participants in that relationship.
You can fine tune the output from your map by setting different attributes on the topicref element. For example, the linking attribute controls how a topic's relationships to other topics are expressed as links, and the toc attribute controls whether the topic shows up in TOC or navigation output.
See appendix for information about this element in OASIS document type shells.
In this example, there are six topicref elements. They are nested and have a hierarchical relationship. bats.dita is the parent topic and the other topics are its children.
<map title="Bats"> <topicref href="bats.dita" type="topic"> <topicref href="batcaring.dita" type="task"></topicref> <topicref href="batfeeding.dita" type="task"></topicref> <topicref href="batsonar.dita" type="concept"></topicref> <topicref href="batguano.dita" type="reference"></topicref> <topicref href="bathistory.dita" type="reference"></topicref> </topicref> </map>
The following attributes are available on this element: Universal attribute group, Link relationship attribute group (with a narrowed definition of href, given below), Attributes common to many map elements, Topicref element attributes group, outputclass, keys, and keyref.
- A pointer to the resource represented by the topicref. See The href attribute for detailed information on supported values and processing implications. References to DITA content cannot be below the topic level: that is, you cannot reference individual elements inside a topic. References to content other than DITA topics should use the format attribute to identify the kind of resource being referenced.