Filtering (DITAVAL)

A DITAVAL file includes, excludes or flags elements with filter attributes. DITAVAL files can be passed into the build process by the dita.input.valfile property or by <ditavalref>.

Sample project: ditaval.zip

map.ditamap

The map.ditamap references the topic.dita. The <topicref> element includes a <ditavalref> element that references the DITAVAL file containing the filter rules. The filters are applied in the scope of their parent element, in this case topic.dita, and its children. This mechansim is called branch filtering.

Note: If the same filter rules should be applied to the whole project, it is recommended to pass the DITAVAL file by defining the dita.input.valfile property.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>map</title>
  <topicref href="topic.dita">
    <ditavalref href="android.ditaval"/>
  </topicref>
</map>

topic.dita

The topic.dita topic contains two <p> elements, both with the filter attribute @platform, but with different values. In this example, the element with the attribute value ios should be filtered out.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic">
  <title>topic</title>
  <body>
    <!-- Will NOT be filtered out -->  
    <p platform="android">android</p>
    <!-- Will be filtered out -->
    <p platform="ios">ios</p>
  </body>
</topic>

android.ditaval

The android.ditaval file contains the filter rules. The <prop> elements represent the filter rules. The @att attribute contains the name of the filter attribute and the @val attribute contains the value of the filter attribute. The @action attribute specifies what should happen to the element (include, exclude, flag).

<?xml version="1.0" encoding="UTF-8"?>
<val>
  <prop action="include" att="platform" val="android"/>
  <prop action="exclude" att="platform" val="ios"/>  
</val>

This DITAVAL file

  • excludes all elements with platform="ios", e.g.
    <p platform="ios">ios</p>
  • includes all elements with platform="android", e.g.
    <p platform="android">android</p>