• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Learning DITA

Free DITA training

Free DITA training

  • Log in
  • Register
  • Newsletter
  • Profile
  • Privacy
  • Home
  • About
  • Courses
  • News
  • Resources
  • Support the site
  • Contact
  • Recordings

The ditaval file

Posted on 12.02.16

Advanced reuse in DITA Lesson 1: Using conditions The ditaval file
Lesson Progress
0% Complete

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

Contributors
  • Simon Bate
  • Jake Campbell
  • Gretyl Kinsey
Previous Topic
Back to Lesson
Next Topic

sidebar

Blog Sidebar

  • Scriptorium logo
    Maximize the value of your content. Read more.
  • Scriptorium logo
    Need DITA help? We offer flat-rate consulting. Get help.
  • Scriptorium logo
    Already in DITA and need support? Contact us.
RSSTwitter

Want to add content? Join the ditatraining GitHub repository.

  • Home
  • Sponsor
  • News
  • Contact
  • Privacy

Maintained by Scriptorium Publishing

Logo and site presentation © 2015-2021 Scriptorium Publishing. Content based on the open-source DITA training project.