Apply Ditaval

Applies filtering to files based on the properties defined in a ditaval file.

The Apply Ditaval command offers two modes for ditaval filtering:

Filter with Conditions - Applies filtering by mapping the ditaval properties to FrameMaker conditional tagging based on the options selected in the Apply Ditaval dialog. Due to the nature of FrameMaker conditions, for complex filtering, this option may not always result in the expected outcome.
Filter by Deletion - Applies filtering by deleting “excluded” content as defined in the selected ditaval file. The result of using this option will often be closer to that of the filtering applied by the DITA-OT.

This command can be used to filter a topic while authoring or for filtering content that has been generated through the Generate Book from Map command. If the command is run on a topic file, the filtering is applied to that file. If a book is active, the filtering is applied to all files in that book.

In order to use this command you must have at least one ditaval file registered with DITA-FMx. A ditaval file is “registered” with DITA-FMx when you use the Ditaval Manager to create new ditaval files or add existing ditaval files. When you run the Apply Ditaval command, the dialog box lists the available ditaval files (those that have been registered).

Important: When applying filtering to the active topic file, keep in mind that the Filter by Deletion option actually deletes content from the file. Because of this it’s recommended that you only run this command on a duplicate file. When using the Filter with Conditions option on the active topic file, the conditional tagging is typically saved to the XML file as processing instructions (PIs). This may also not be a desirable situation. Use this command with caution on active topic files.

Figure 1. DITA-FMx Apply Conditions dialog box

Filtering by deletion

When using the Filter by Deletion option, the rest of the options in the dialog are disabled; they only apply to the filter with condition option. The Filter by Deletion option deletes all elements with filtering attributes that match those specified with “exclude” prop values in the ditaval file.

Filtering with conditions

When using the Filter with Conditions option, the properties assigned to the ditaval action values (“exclude”, “include” and “flag”). The settings in the three “action=” areas define the condition name and the visibility of the conditions that are applied when a prop action attribute matches the specified type.

For each prop element in a ditaval file the action attribute specifies either to exclude, include, or flag elements with matching attributes and values. When a ditaval file is applied as conditions in a FrameMaker file, elements are matched based on the att and val attributes, and a named condition is applied to each element. In the Apply Conditions dialog you specify that the condition name is defined as a fixed string (such as “Exclude”, “Include” or “Flag”) or that it is defined based on a combination of the att and val attribute values. For example, given the following line from a ditaval file, if the condition name is defined by the att and val attributes, it would be “audience=admin.”

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

The condition visibility options are Show, Hide, and Default. If set to Show or Hide, the conditions will be shown or hidden accordingly. However, if Default is selected, the condition visibility will be defined by the settings in the template assuming that the condition is already defined.

This can also be done automatically during the Map to Book conversion process by selecting the Apply Ditaval option in the Book Build Settings dialog found in the DITA Options dialog.

Note: The Apply Ditaval as Conditions command does not necessarily result in conditional filtering that matches that of the DITA Open Toolkit. The conditions are applied properly based on the filtering attribute values, but the default hide/show logic of FrameMaker conditions is not the same as the used by the OT. It may be possible to achieve this filtering through the use of Boolean conditional expressions.