Filtering Profiling Values with a DITAVAL File

You can use a DITAVAL filter file to control the filtering or flagging of profiled content or to identify which values are to be used for conditional processing during a particular output.

DITAVAL Filtering Use-Case

Suppose that a medical publication uses the audience profiling attribute to profile the content for the following types of users: therapist, physician, and surgeon. Suppose that in the output, you want to exclude any content that is profiled as surgeon value for the @audience attribute.

You could use a DITAVAL filter file to exclude anything that is profiled as surgeon:

<val>
     <prop action="exclude" att="audience" val="surgeon"/>
</val>

If you then transform the main DITA map and specify the DITAVAL filter file in the transformation scenario, the output will exclude anything that is profiled as surgeon).

DITAVAL Filter File Editor in Author Mode

The Author editing mode in Oxygen XML Author Eclipse plugin offer a simple and intuitive editor for creating or modifying DITAVAL files. It provides a series of drop-down menus and text fields that allow you to easily define the filters.

Figure 1. DITAVAL File Editor in Author Mode

Use the +... button to display a drop-down list that contains elements that you can add at that particular location in the DITAVAL file. Clicking this button at the top (next to the DITAVAL FILTER File title, allows you to insert the following elements:

Style Conflict - Inserts a <style-conflict> element that declares behavior to be used when one or more flagging methods collide on a single content element. You can use the simple drop-down menus to select values for the @foreground-conflict-color and @background-conflict-color attributes.
Filter - Inserts a <prop> element that identifies an attribute to apply a filtering action on. The possible actions that you can select are include, exclude, passthrough, and flag. If you select the flag action, you can use the drop-down menus to select values for the @style, @color, and @background attributes.
Flag - Inserts a <revprop> element that Identifies a value in the @rev attribute that should be flagged in some manner. The allowed actions are include, passthrough, and flag. If you select the flag action, you can use the drop-down menus to select values for the @style, @color, @background, and @changebar attributes.

See the DITAVAL Element Specifications for more details about the allowed filters and flags.

How to Create a DITAVAL Filter File

To create a DITAVAL filter file, follow these steps:

Go to File > New.
Scroll to the Framework templates > DITA folder.
Select the Filter template file and click Create.
Define your filters in the DITAVAL file (in Text or Author mode).
Save the DITAVAL file.

Result: The DITAVAL filter file can now be used for all of the following:

To apply a reference to the DITAVAL file in a Profiling Condition Set using the Use DITAVAL File option in the Condition Set configuration dialog box.
You can use the Import from DITAVAL option in the Attributes and Condition Sets preferences page to use the DITAVAL file to define profiling attributes.
You can use the DITAVAL file to apply the filters to the output by specifying the DITAVAL file in the transformation scenario.
You can use the filter file in the DITA Map Completeness Check dialog box when validating your DITA map.
DITAVAL files are also used when working with the DITA 1.3 Branch Filtering mechanism. For more details, see: Working with DITA 1.3 Branch Filtering.
You can define the colors and styles to be used for rendering profiled condition sets in Author mode and the DITA Maps Manager view by using a Flag filter in the DITAVAL file.