When generating output from sources that use the conditional attributes, you need to tell the output processor what to hide and what to show.
In most output generators, you use a ditaval file, which indicates which attributes with what values to filter out of your content. (Some output generators do not use ditaval files; they use filtering mechanisms of their own design, but the principles are still the same.)
The ditaval file is an XML file, but it is not a DITA file; that is, it does not use the DITA doctypes or elements. In DITA 1.2, the ditaval file is not included in DITA maps; the file path to your ditaval file is passed to output generators using a command argument. In DITA 1.3, you can use the <ditavalref> element to include a ditaval file in a DITA map.
The name of your ditaval file is up to you, although it’s a good idea to use a filename that indicates the file’s purpose. Typically you store the ditaval file along with your maps, although it can reside anywhere that is accessible to your output generator.
Typically you will have one ditaval file for each main map or bookmap file.
The root element in the ditaval file is the <val> element; in a typical file, the <val> element contains one or more <props> elements:
<val> <prop att="platform" val="iphone" action="exclude" /> </val>
This example shows the basic form of a <prop> element.
- The att attribute indicates one of the conditional attributes. In this case, platform.
- The val attribute indicates what value to match in the att attribute. In the example, all elements where platform=”iphone” are filtered.
Note: When specifying the val attribute, case is important. A val attribute containing “iPhone” would not match a conditional attribute with the value “iphone”.
- The action attribute indicates what to do when a match for the attribute and value is found. In this case, any element that contains platform=”iphone” is excluded from output (that is, it is hidden).
Note: The DITA sources shown in the following examples are in the downloadable samples file reuse_advanced_samples.zip. The DITA file is c_filtering_and_flagging.dita; the ditaval file is domestic.ditaval.
Conditional filtering example
In this example DITA topic, the second <p> element contains a sentence within a <ph> (phrase) element. The product conditional attribute has the value “wild_ducks”:
<p>For the healthiest ducks, we recommend using our feeds.</p> <p>All our duck feeds are composed of cracked corn, oats, rice, and milo seed. <ph product="wild_ducks">Our wild duck feed also includes worm meal and fish meal. </ph> </p> <p>All feeds are available in 5, 10, and 20 pound sacks.</p>
If you generate output from this content without using a ditaval file, it looks like this:
But if you use this ditaval file to filter out content where product=”wild_ducks”:
<val>
<prop att="product" val="wild_ducks" action="exclude" />
</val>
The output looks like this:
For more information about ditaval files and how to use them for filtering, see http://docs.oasis-open.org/dita/v1.2/os/spec/common/about-ditaval.html#ditaval