3.1.2.1.10 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:

Contains

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:

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 3.4.1.8 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 3.4.1.3 univ-atts attribute group

     

global-atts attribute group (xtrf, xtrc)

A set of related attributes, described in 3.4.1.2 global-atts attribute group

     

class, outputclass

Common attributes described in 3.4.1.9 Other common DITA attributes

     

Previous Topic:  3.1.2.1.9 relheader

Next Topic:  3.1.2.2 Map group elements

Parent Topic:  3.1.2.1 Basic map elements

Sibling Topics:

3.1.2.1.1 map

3.1.2.1.2 topicref

3.1.2.1.3 topicmeta

3.1.2.1.4 anchor

3.1.2.1.5 navref

3.1.2.1.6 reltable

3.1.2.1.7 relrow

3.1.2.1.8 relcell

3.1.2.1.9 relheader