Example: Single <ditavalref> in a reference to a map

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

Example

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 1. Map fragment
<topicref href="parent.dita">
  <topicref href="other.ditamap" format="ditamap">
    <ditavalref href="some.ditaval"/>
  </topicref>
</topicref>
Figure 2. 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.