relcolspec

The <relcolspec> element is used to define a column in a relationship table. The <relcolspec> element may be used to set default 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> 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: These models represent only the default document types distributed by OASIS. Actual content models will differ with each new document type.

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