<topicref>

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.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- map/topicref

Example

This section is non-normative.

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>

Content model

<topicmeta>?, (<anchor> | <data> | <data-about> | <navref> | <topicref>)*

Contained by

<anchorref>, <keydef>, <map>, <relcell>, <relcolspec>, <topicgroup>, <topichead>, <topicref>, <topicset>, <topicsetref>

In order
  1. Optional <topicmeta>
  2. Zero or more of the following
    • <anchor>
    • <data>
    • <data-about>
    • <navref>
    • <topicref>

Contained by

  • <anchorref>
  • <keydef>
  • <map>
  • <relcell>
  • <relcolspec>
  • <topicgroup>
  • <topichead>
  • <topicref>
  • <topicset>
  • <topicsetref>

Inheritance

- map/topicref

The <topicref> element is a base element type. It is defined in the map module.

Attributes

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.

@href
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.
@href
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.