Table of Contents
User Guide
Filtering
Filtering Overview
Use Filtering features to conditionalize content.
Filtering Elements in a Topic
Use the Topic Editor to set values and filter elements in a topic for conditional publishing.
Filtering Entire Topics or Sections of a Map
Use the Map Editor to set attributes and filter entire topics or sections of a map for conditional publishing.
Previewing Filtered Output 
Use the Topic Editor to preview and modify the view settings of filtered output.
Filtering Overview

Use Filtering features to conditionalize content.
Filtering is a powerful capability in DITA that enables you to identify content that should only appear in certain versions of your output.
Let’s look at some examples of when to use profiling and filtering:
  • You are documenting a software package that has different features or functionality for the Windows and Linux platforms
  • You are creating an electronic document output that hides complex technical information from basic users but displays it to advanced users
  • Your company produces vehicles with the driver controls on the right for some markets and on the left for others.
Instead of keeping two separate document sets for the content, you can keep the content in one topic and identify attributes for the elements. These attributes are used to include or exclude the content during output.
DITA provides several built-in attributes for specifying the Audience, Platform, Product, and Other Properties for an element in a topic or an element in a map. These are called Select Attributes, or selectatts for short. They are essentially predefined attributes in DITA that you can set to any value. For instance, you can set the Audience selectatt to “Novice” or the Platform selectatt to “Windows”.
At publish time, you can define the values for each selectatt that you want to apply using a DITAVal file. A DITAVal file can contain sets of variables and configuration information that you want to use whenever you publish a DITA map, including selectatts, output formats, and locales. 

Filtering at the Element Level

You can filter elements in a topic using the Properties Pane in the Topic Editor. For example, you can select a bullet list and modify the Audience to “Novice”, so the bullet list will only appear in the output if the Novice Audience is configured to be included.
To learn more, see Filtering Elements in a Topic.

Filtering Entire Topics or Sections of a Map

You can also filter an element in a map using the Edit Properties window in the Map Editor. For example in the element’s properties, you can modify the Product to “Mobile”, so the topic will only appear in the output if Mobiles Products are configured to be included.
Filtering Elements in a Topic

Use the Topic Editor to set values and filter elements in a topic for conditional publishing.
You have a topic open and want to set Filtering Properties values for topic elements.
  1. Place your cursor in the element you want to filter.

    Step Information
    Note:It is a best practice to profile entire elements, not just individual words or phrases. This is especially important when localizing the content, since a complete sentence is required to provide sufficient context for accurate translation memory and machine translation matching. This is true even if some text is duplicated across alternative elements for different conditions.
  2. Click Properties.

    Expected Result
    The Properties Pane displays.
  3. Navigate to the Filtering Properties that you want to define. 

    Step Information
  4. Enter the values for each Filtering Properties that defines the condition in which the element will be displayed. 

    Example
    In this example, we set the Audience Filtering Property to “Novice” for the first item in the list. The item will be published only when Audience=”Novice” at publish.
The Filtering Properties values are set for the topic element.

Note:Depending on the action defined for a specific value at publish time, the information is either flagged, excluded, or included. If no action is specified for a specific value, the default is to include the content (unless your publishing profile sets the default to exclude).
Filtering Entire Topics or Sections of a Map

Use the Map Editor to set attributes and filter entire topics or sections of a map for conditional publishing.
You have a map open and set the Filtering Properties for a topic or entire section of the map.
  1. Right-click the element you want to set the Filtering Properties for and select Edit Element Attributes.

    Step Information
    Expected Result
    The Edit Properties window displays.
  2. Enter the values for each Filtering Properties that defines the condition in which the element will be displayed. 

    Example
    If the topic is only intended for administrators, then enter “Administrator” in the Audience field.
    Step Information
    Note:The default properties for filtering are: audience, rev, platform, product, and otherprops.
  3. Click Save.
The Filtering Properties values are set for the element.
Note:Depending on the action defined for a specific value at publish time, the information is either flagged, excluded, or included. If no action is specified for a specific value, the default is to include the content (unless your publishing profile sets the default to exclude).
Previewing Filtered Output 

Use the Topic Editor to preview and modify the view settings of filtered output.
You have a topic open and want to modify the view settings of filtered output for a select attribute value. 
  1. Navigate to the filtered element in your topic. 

    Step Information

    Any document with defined values for select attributes will display in a label in the left margin of the Topic Editor.  The label shows the value or values that have been defined for that element.

  2. Click on a label.

    Step Information
    Expected Result
    The Conditional View Settings window displays.
  3. For each select attribute value, do any of the following:

    1. To show the filtered output, check Shows.
    2. To grey the filtered output, check Greyed.
    3. To hide the filtered output, check Hidden.
  4. Click Apply.

    Expected Result
    If Shows was selected, filtered output displays alongside unfiltered content:
    If Greyed was selected, filtered output is greyed:
    If Hidden was selected, filtered output is hidden:
The view settings of filtered elements are modified.