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.
- 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.
See appendix for information about this element in OASIS document type shells.
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
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>
- 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.
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.