Tips for filtering and conditionalizing content in topic files or maps.
DITA-FMx provides many ways to filter the content in your DITA files. The auto-conditionalizing options apply conditions to elements each time you open a file, and the Apply Ditaval as Conditions command can approximate the effect of applying a ditaval file to a topic file or book. You can also achieve filtering when generating a FM book from a DITA map by modifying the Book application’s read-write rules file.
There are four options for applying conditions to elements on file open. The Conditionalize Prolog and Conditionalize Comments options apply the DITA-Prolog and DITA-Comment conditions to the respective elements each time you open a topic file. The Conditionalize data, data-about, and area option applies the DITA-Data condition to data, data-about, and area elements when opening a topic file or DITA map file.The Conditionalize Topicmeta and Bookmeta option applies the DITA-Topicmeta to the topicmeta element when opening a DITA map file. On file save, these conditions are stripped (all other conditions you may apply will honor the Conditional Text setting in the structure application definition).
The term “Conditionalize” does not necessarily mean to “hide,” it just means that the associated condition will be applied to the elements. It is up to you to set the hide/show state as well as the color and style for these conditions (in the structure application template).
When any of these options are enabled, the plugin does a “show all” then a “hide” of the appropriate conditions when the XML or FM file is opened. If the file makes extensive use of conditions, this may result in the addition of blank pages at the end of the document. For XML files, this is not a problem since the blank pages are not saved, but if you’re working on generated FM files, you may end up with extra blank pages that you can’t get rid of (each time you save then reopen, the blank pages will reappear). If this is the case, you should disable the auto-conditionalizing options when doing final pagination on generated FM files.
In order to filter content in FM files based on a ditaval file, you should use the Apply Ditaval as Conditions command. Before using this command you need to first create the ditaval file (using the Ditaval Manager or other means), then register it with the Ditaval Manager. Once the ditaval file has been registered with DITA-FMx, you can use it with the Apply Ditaval as Conditions command. Detailed information about using this command is available in the Using the Apply Ditaval as Conditions Command topic.
Although, not a requirement, it is best to use this command only on generated FM files, not on your DITA XML files. If you use it on the XML files, the conditions are saved to the XML as processing instructions (PIs) and will persist in the state set the next time you open the file (this persistence is dependent on the Conditional Text setting in the associated structure application definition).
When you generate an FM book from a DITA map, these PIs are filtered out during the import XSLT processing and not included in the generated FM files. However, any conditions that have been applied to content that is the source of a conref, will appear in the generated FM files because the conref source is not passed through the import XSLT processing, but pulled in by the conref resolution process which happens after the initial topic file aggregation. This results in an FM file with some conditions that appear to have survived the conversion while other have not. This confusing situation can be avoided by not applying conditions to the XML files.
Regardless of whether you have applied conditions to the XML files or not, you can still run the Apply Ditaval as Conditions command to apply conditions based on the properties in a ditaval file.
If the filtering provided by the Apply Ditaval as Conditions command doesn’t result in the required filtering for your documents, you can make use of FrameMaker’s Filter by Attribute build expressions when generating a book from a map.
To make use of this feature, you should start by developing (and testing) the attribute build expression in a generated FM file (the result of the book-build process). When you’ve created the necessary build expression, import it into your Book template (or appropriate component templates) using and select the Filter by Attribute Settings option. In addition to the named build expression, your template must define the condition you plan to assign to the filtered content.
Use of this feature requires that you’re using a book-build INI file. In the BookBuildOverrides section, add an entry named FilterByAttribute. Assign the build expression name and the condition name (separated with a greater-than symbol) as the value to this INI entry using the syntax: BUILD-EXPRESSION>CONDITION-NAME. For example, if your build expression is named “Print-Filter” and the condition is “FilteredContent”, the INI entry would look like the following:
[BookBuildOverrides] FilterByAttribute=Print-Filter>FilteredContent ...
Because the use of this feature is a replacement for ditaval filtering, if this entry is used in the book-build INI file, any specified ditaval filtering is ignored for content filtering. When the FilterByAttribute feature is in use, ditaval filtering is still used for the filtering of key definitions, so it is important to maintain both.
In the future, DITA-FMx may provide a mapping from ditaval to attribute build expressions, but for now this is left to the user to develop.
If there are certain elements that you want to exclude from your generated FM book files, use the “drop” rule. For example, if you want to exclude the shortdesc element from your generated files, add the following rule to the Book application’s rules file:
element "shortdesc" drop;
This results in the shortdesc element being removed from the generated FM files while it remains in the source topic files.