`<relcolspec>`

A column specification in a relationship table column that provides default attribute values for the references in that column of a relationship table.

Usage information

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.

Adding a <topicref> element to the <relcolspec> element defines a relationship between the topics that are contained within 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.

Rendering expectations

When a <title> element exists inside of the <relcolspec> element, the content of the <title> element is intended to be 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 specifies a navigation title, that navigation title is used for the label.
If the <relcolspec> element contains a <topicref> element that does not specify a navigation title but does reference a DITA topic, the label is derived from the navigation title of the referenced topic or, lacking that, the title of 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.

Processing expectations

When values are specified for attributes of <relcell> or <relrow> elements, those values override those defined for <relcolspec> attributes. Values specified for attributes of <relcolspec> elements override those defined for the <reltable> element.

Attributes

The following attributes are available on this element: universal attributes and common map attributes (without @keyscope or @collection-type), @type, @scope, and @format.

Examples

The following section contains examples of how the <relcolspec> element can be used.

Figure 1. Enforcing concept, type, and reference types with <relcolspec>

The following code sample shows how a <relcolspec> element can be used to define the types of topics that are referenced in a column. 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>

Figure 2. Relationship table column headers with topics and titles

The following code sample shows how topics and titles can be specified in a column header for relationship table column header:

<reltable>
  <relheader>
    <relcolspec type="task">
      <topicref href="tbs.dita">
        <topicmeta><navtitle>Troubleshooting</navtitle></topicmeta>
      </topicref>
    </relcolspec>
    <relcolspec type="reference">
      <topicref href="msg.dita">
        <topicmeta><navtitle>Messages</navtitle></topicmeta>
      </topicref>
    </relcolspec>
  </relheader>
  <relrow>
    <relcell>
      <topicref href="debug_login.dita"/>
        <topicmeta><linktitle>Debugging login errors</linktitle></topicmeta>
      </topicref>
    </relcell>
    <relcell>
      <topicref href="login_error_1.dita">
        <topicmeta><linktitle>Login not found</linktitle></topicmeta>
      </topicref>
    </relcell>
  </relrow>
  <relrow>
    <relcell>
      <topicref href="checking_access.dita">
        <topicmeta><linktitle>Checking access controls</linktitle></topicmeta>
      </topicref>
    </relcell>
    <relcell>
      <topicref href="login_error_2.dita">
        <topicmeta><linktitle>Login not allowed</linktitle></topicmeta>
      </topicref>
    </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 typically will be expressed as a link from each to the other. An application might 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.