`<topicsetref>`

The <topicsetref> element references a <topicset> element. The referenced <topicset> element can be defined in the current map or in another map.

When possible, applications should treat the referenced <topicset> as an independent unit. For example, an application that renders DITA for a dynamic navigation platform might generate a reusable navigation structure for each <topicset>, and each <topicsetref> is retained as a reference to that structure. This differs slightly from the processing of the @conref attribute, which results in a literal copy of the referenced content.

For situations that do not support reusing a topic set as an independent unit, such as a rendered PDF, applications MAY resolve the <topicsetref> element as for other <topicset> (or <topicref>) elements that have the @format attribute set to "ditamap".

As with other cases where the attribute format="ditamap" is specified or used as a default, the use of topic references nested inside of <topicsetref> is undefined.

Content models

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

Inheritance

+ map/topicref mapgroup-d/topicsetref

Example

The sql-tutorial.ditamap file contains a <topicset> element that groups together several topics that collectively comprise an overview of SQL.

Figure 1. DITA map that contains a <topicset> element

<!-- Excerpt from sql-tutorial.ditamap -->
<topicset id="sqlbasics" href="sqlOverview.dita">
  <topicref href="sqlSelection.dita"/>
  <topicref href="sqlJoin.dita"/>
  <topicref href="sqlFilter.dita"/>
  <!-- ... -->
</topicset>

Another map can include that topic set, in addition to content related to programming with JDBC.

Figure 2. DITA map that contains a <topicsetref> element

<topichead navtitle="Mastering JDBC">
  <topicsetref href="sql-tutorial.ditamap#sqlbasics"/>
  <topicref href="jdbcPrepare.dita"/>
  <!-- ... -->
</topichead>

A reader of the JDBC information will see the content integrated as a single unit.

Figure 3. Result of the reuse

<topichead navtitle="Mastering JDBC">
  <topicset id="sqlbasics" href="sqlOverview.dita">
    <topicref href="sqlSelection.dita"/>
    <topicref href="sqlJoin.dita"/>
    <topicref href="sqlFilter.dita"/>
    <!-- ... -->
  </topicset>
  <topicref href="jdbcPrepare.dita"/>
  <!-- ... -->
</topichead>

Attributes

The following attributes are available on this element: Universal attribute group, Link relationship attribute group (with narrowed definitions of @href, @format, and @type, given below), Attributes common to many map elements, Topicref element attributes group, outputclass, @keys, and @keyref.

@href: A pointer to the <topicset> represented by <topicsetref>. See The href attribute for detailed information on syntax.
@format: The @format attribute identifies the format of the resource being referenced. For the <topicsetref> element, this attribute defaults to "ditamap", because the element typically references a branch of a map. See The format attribute for details on other supported values.
@type: Describes the target of a reference. For the <topicsetref> element, this attribute defaults to "topicset". See The type attribute for detailed information on other supported values and processing implications.