Example: Single ditavalref in a reference to a map

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

version
1.3
author
OASIS DITA Technical Committee

Using a ditavalref element in a reference to a map is equivalent to setting filtering conditions for the referenced map.

In the following example, other.ditamap is referenced by a root map. The ditavalref element indicates that all of the content in other.ditamap should be filtered using the conditions specified in the some.ditaval document.

Figure. Map fragment
<topicref href="parent.dita">
  <topicref href="other.ditamap" format="ditamap">
    <ditavalref href="some.ditaval"/>
  </topicref>
</topicref>
Figure. Contents of other.ditamap
<map>
  <topicref href="nestedTopic1.dita">
    <topicref href="nestedTopic2.dita"/>
  </topicref>
  <topicref href="nestedTopic3.dita"/>
</map>
This markup is functionally equivalent to applying the conditions in some.ditaval to the topics that are referenced in the nested map. For the purposes of filtering, it could be rewritten in the following way. The extra topicgroup container is used here to ensure filtering is not applied to parent.dita, as it would not be in the original example:
<topicref href="parent.dita">
  <topicgroup>
    <ditavalref href="some.ditaval"/>
    <topicref href="nestedTopic1.dita">
      <topicref href="nestedTopic2.dita"/>
    </topicref>
    <topicref href="nestedTopic3.dita"/>
  </topicgroup>
</topicref>

For the purposes of filtering, this map also could be rewritten as follows.

<topicref href="parent.dita">
  <topicref href="nestedTopic1.dita">
    <ditavalref href="some.ditaval"/>
    <topicref href="nestedTopic2.dita"/>
  </topicref>
  <topicref href="nestedTopic3.dita">
    <ditavalref href="some.ditaval"/>
  </topicref>
</topicref>

Filtering based on the ditavalref element applies to the containing element and its children, so in each case, the files nestedTopic1.dita, nestedTopic2.dita, and nestedTopic3.dita are filtered against the conditions specified in some.ditaval. In each version, parent.dita is not a parent for the ditavalref, so it is not filtered.