<relcolspec>

The <relcolspec> element is used to define a column in a relationship table. The <relcolspec> element can be used to set default attribute values for the <topicref> elements in the column.

You can use the <relcolspec> element to set default values for the attributes of the topics that are referenced in the column. For example, when you set the @type attribute to "concept," all <topicref> elements in the column that do not have a @type attribute specified are treated as concepts. When values are specified for attributes of <relcell> or <relrow> elements, those values are inherited before those defined for <relcolspec> attributes. Values specified for attributes of <relcolspec> elements are inherited before those defined for the <reltable> element.

Beginning with DITA 1.2, you also can add <topicref> elements to the <relcolspec> element; this defines a relationship between the topics that are referenced in the <relcolspec> element and the topics that are referenced in the column of the relationship table. Note that this does not define a relationship between two cells in the same column; the only new relationship is between <topicref> targets in a <relcell> and <topicref> targets in that column's <relcolspec>.

Also beginning with DITA 1.2, if you add a <title> element to the <relcolspec> element, the content of the <title> element is used as the label for the related links that are defined and generated by the column. If the <title> element is not present, the labels for the related links are generated in the following ways:
  • If the <relcolspec> element contains a <topicref> element that references a non-DITA resource, the value of the <topicref> element's navigation title is used for the label.
  • If the <relcolspec> element contains a <topicref> element that references a DITA resource and the @locktitle attribute is set to "yes," the value of the <topicref> element's navigation title is used for the label.
  • If the <relcolspec> element contains a <topicref> element that references a DITA resource and the @locktitle attribute is missing or set to "no," the label is derived from the <navtitle> or <title> element specified within the topic.
  • If no title is specified and no <topicref> is present in the <relcolspec>, a rendering tool might choose to generate a title for the links generated from that column.

Content models

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

Inheritance

- map/relcolspec

Example

This section is non-normative.

In this example, a relationship table is defined with three columns; one for "concept", one for "task", and one for "reference". Three cells are defined within one row. The first cell contains one concept topic: puffins.dita. The second cell contains two task topics: puffinFeeding.dita and puffinCleaning.dita. The third cell contains a reference topic: puffinHistory.dita. Setting the @type on each column allows (but does not require) processors to validate that the topics in each column are of the expected type.

<map>
 <reltable>
  <relheader>
   <relcolspec type="concept"/>
   <relcolspec type="task"/>
   <relcolspec type="reference"/>
  </relheader>
  <relrow>
   <relcell><topicref href="puffins.dita"/></relcell>
   <relcell>
     <topicref href="puffinFeeding.dita"/>
     <topicref href="puffinCleaning.dita"/>
   </relcell>
   <relcell>
     <topicref href="puffinHistory.dita"/>
   </relcell>
  </relrow>
 </reltable>
</map>

Example with column titles

This section is non-normative.

Consider the following relationship table:

<reltable>
  <relheader>
    <relcolspec type="task">
      <topicref navtitle="Troubleshooting" href="tbs.dita" locktitle="yes"/>
    </relcolspec>
    <relcolspec type="reference">
      <topicref navtitle="Messages" href="msg.dita" locktitle="yes"/>
    </relcolspec>
  </relheader>
  <relrow>
    <relcell>
      <topicref navtitle="Debugging login errors" href="debug_login.dita"/>
    </relcell>
    <relcell>
      <topicref navtitle="Login not found" href="login_error_1.dita"/>
    </relcell>
  </relrow>
  <relrow>
    <relcell>
      <topicref navtitle="Checking access controls" href="checking_access.dita"/>
    </relcell>
    <relcell>
      <topicref navtitle="Login not allowed" href="login_error_2.dita"/>
    </relcell>
  </relrow>
</reltable>
In addition to the relationships defined by the rows in the relationship table, the following relationships are now defined by the columns in the relationship table:
  • tbs.dita <–> debug_login.dita
  • tbs.dita <–> checking_access.dita
  • msg.dita <–> login_error_1.dita
  • msg.dita <–> login_error_2.dita

Ignoring the headers for a moment, the <reltable> here would ordinarily define a two-way relationship between debug_login.dita and login_error1.dita. This will typically be expressed as a link from each to the other. An application MAY render the link with a language-appropriate heading such as "Related reference", indicating that the target of the link is a reference topic.

The headers change this by specifying a new title. In the second column, the <topicref> specifies a title of "Messages", which should now be used together with the link to anything in that column. So, a generated link from debug_login.dita to login_error1.dita should be rendered together with the title of "Messages". How this is rendered together with the link is up to the application.

Content model

<title>?, <topicmeta>?, <topicref>*

Contained by

<relheader>

In order
  1. Optional <title>
  2. Optional <topicmeta>
  3. Zero or more <topicref>

Contained by

  • <relheader>

Inheritance

- map/relcolspec

The <relcolspec> 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, Attributes common to many map elements (without @keyscope attribute), and outputclass. This element also uses @type, @scope, and @format from Link relationship attribute group.