<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> 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
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.ditatbs.dita<–>checking_access.ditamsg.dita<–>login_error_1.ditamsg.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.
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.