relcolspec
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> elements. 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 <recolspec> 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 points to a non-DITA source, the value of the topicref's navtitle element or attribute is used for the label.
- If the <relcolspec> element contains a <topicref> element that points to a DITA source and the locktitle attribute is set to "yes," the value of the topicref's navtitle element or attribute is used for the label.
- If the <relcolspec> element contains a <topicref> element that points to a DITA source 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 may choose to generate a title for the links generated from that column.
Contains
Note
| Doctype | Content model |
|---|---|
| map (base), bookmap | ( (title) (optional) then (topicmeta) (optional) then (topicref or anchorref or keydef or mapref or topicgroup or topichead or topicset or topicsetref) (any number) ) |
| map (technical content) | ( (title) (optional) then (topicmeta) (optional) then (topicref or (anchorref or keydef or mapref or topicgroup or topichead or topicset or topicsetref) or (glossref) ) (any number) ) |
| classifyMap | ( (title) (optional) then (topicmeta) (optional) then (topicref or (topicsubject or topicapply) or (anchorref or keydef or mapref or topicgroup or topichead or topicset or topicsetref) ) (any number) ) |
| subjectScheme | ( (title) (optional) then (topicmeta) (optional) then (topicref or (anchorref or keydef or mapref or topicgroup or topichead or topicset or topicsetref) ) (any number) ) |
| learningBookmap, learningMap | ( (title) (optional) then (topicmeta) (optional) then (topicref or anchorref or keydef or mapref or topicgroup or topichead or topicset or topicsetref or learningObject or learningGroup) (any number) ) |
Contained by
| Doctype | Content model |
|---|---|
| map (base), map (technical content), bookmap, classifyMap, subjectScheme, learningBookmap, learningMap | relheader |
Inheritance
- map/relcolspec
Example
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>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, but need not, 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.
Attributes
| Name | Description | Data Type | Default Value | Required? |
|---|---|---|---|---|
| topicref-atts attribute group (collection-type, processing-role, type, scope, locktitle, format, linking, toc, print, search, chunk) | A set of related attributes. See topicref-atts, topicref-atts-no-toc, and topicref-atts-without-format attribute groups. | |||
| univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups) | A set of related attributes, described in univ-atts attribute group | |||
| global-atts attribute group (xtrf, xtrc) | A set of related attributes, described in global-atts attribute group | |||
| class, outputclass | Common attributes described in Other common DITA attributes |