Example: Single <ditavalref> on a branch

A single <ditavalref> element can be used to supply filtering conditions for a branch.

Consider the following DITA map and the DITAVAL file that is referenced from the <ditavalref> element:

input.ditamap:

<map>
  <topicref href="intro.dita"/>
  <topicref href="install.dita">
    <ditavalref href="novice.ditaval"/>
    <topicref href="do-stuff.dita"/>
    <topicref href="advanced-stuff.dita" audience="admin"/>
    <!-- more topics -->
  </topicref>
  <!-- Several chapters worth of other material -->
</map>

Contents of novice.ditaval

<val>
  <prop att="audience" val="novice" action="include"/>
  <prop att="audience" val="admin" action="exclude"/>
</val>

When this content is published, the following processing occurs:

  • The first topic (intro.dita) does not use any of the conditions that are specified in novice.ditaval. It is published normally, potentially using other DITAVAL conditions that are specified externally.
  • The second topic (install.dita) is filtered using any external conditions as well as the conditions that are specified in novice.ditaval.
  • The third topic (do-stuff.dita) is filtered using any external conditions as well as the conditions that are specified in novice.ditaval.
  • The fourth topic (advanced-stuff.dita) is removed from the map entirely, because it is filtered out with the conditions that are specified for the branch.

In this example, no resources are renamed based on the <ditavalref> processing.

Note: In cases where the original resource names map directly to names or anchors in a deliverable, the absence of renaming ensures that external links to those topics are stable regardless of whether a DITAVAL document is used.
Parent topic: Examples of branch filtering