Filter By Attribute

About Filter By Attribute

Elements in a structured document can have one or more attributes associated with them. Using FrameMaker, you can filter a structured document based on the value of these attributes. Other XML applications may also use the same attribute-value pair to filter the documents. In this way, single sourcing workflows can be preserved across other XML applications.

The Filter by Attribute feature simplifies the task of filtering a structured document for complex output scenarios. You define a filter using a Boolean expression containing attribute-value pairs. You can create multiple filters, save them, and use them for filtering a document based on different output scenarios.

When a filter is applied to the document, elements that have filter attributes that do not meet the filter criteria are filtered out. You can specify how the filtered out content is treated, as hidden, highlighted with a color, or applied with a condition tag. When an element is filtered out, all the child elements are also filtered out.

Each attribute can have more than one value defined, each with its own conditions, such as Equals To, Any, and Contains Only. You can provide a list of values with the delimiter that you defined for attribute settings.

Note: You cannot filter a document based on Conditional Tags and Attribute values simultaneously.

The following table compares the Show/Hide feature using Conditional Text and the Show/Hide feature using Filter By Attribute.

Conditional Text

Filter By Attribute

Based on conditional tags

Based on attributes

Must be defined in a document

Exists in a structured document

Condition indicators are available to visually display the content, based on various conditions

No indicators

Only one expression can be saved at a time

Multiple expressions can be saved at a time

Available in both structured and unstructured FrameMaker

Available in structured FrameMaker only

(unstructured documents do not have elements and attributes)

Allows hiding an entire document, resulting in an empty-content document

Does not allow the hiding of the entire document, as it does not allow hiding of the root element

Allows selection of even the smallest portion of a document for hiding

The smallest unit that can be hidden using this feature is an element.

Each condition tag has two options to choose from: SHOW or HIDE

Allows better level of granularity in terms of creating a hide condition, because an attribute can have several values (based on its definition). Hence, each attribute value has a separate SHOW or HIDE possibility.

Note: The conditional indicators are disabled when a filter is used. It can be enabled only when no filter is applied to the document.

Build a filter

A filter is defined by a Boolean expression of attribute-value pairs. You can build a filter using the Build Expression dialog box, which provides a simple interface to build the expression using Boolean operators. You can define attribute-value pairs using the Define Attribute Values dialog box. You can select multiple values for each attribute.

You can save a filter as a named expression. You can build and save multiple filter expressions in a structured document. However, you can apply only one filter at a time. The last filter you apply in a document is the active filter.

Use the Manage Attribute Expressions dialog box to manage the filters.

  1. Select Special > Filter By Attribute. The Manage Attribute Expressions dialog box appears.

  2. Click New. The Build Expression dialog box appears.

  3. Enter a unique name for the filter in the Expression Tag field.

  4. Select an attribute from the Attributes list.

  5. Specify a value in the New Value field, and click Add. The new attribute value is included in the Defined Values list.

    If you want to remove a value, select it in the Defined Values list, and then click Delete. You can add multiple values to an attribute, each with its own conditions such as Equals To, Any, or Contains Only.

    Note: Attribute names are case-sensitive, but attribute values are not case sensitive.
  6. Click Add Attribute to include the attribute in the Expression list.

    Note: Use the Clear button to delete all expressions in the Expression area.
  7. Click a button to insert a Boolean operator in the expression. You can build a complex expression through the Boolean operators and multiple attribute-value pairs. Click Clear to clear the expressions built.

  8. Click OK to close the Build Expressions dialog box. The new expression is added to the Manage Attribute Expression dialog box. Click OK to complete the procedure.

Guidelines for building a filter

Keep in mind the following points when building a filter:

  • Ensure that you enter valid attributes in the filter. All valid attributes are listed in the Attributes list of the Build Expression dialog box.

  • Ensure that when you supply more than one value to the attribute, you are using the custom delimiter that you defined for attribute in the attribute Configuration File Settings.

  • Enclose the value of the attribute in double quotation marks.

    Correct: (Language="French" OR Language="German" OR Language="Japanese")

    Incorrect: (Language=French OR Language=German OR Language=Japanese)

    Note: FrameMaker doesn’t support expressions where the attribute value is missing. For example, “(Language=“”)” is not supported in an expression.
  • By default FrameMaker encloses all attribute-value pairs within parentheses. All attribute-value pairs for a specific attribute are placed within the same pair of parentheses. To place the attribute-value pairs for a specific attribute in different pairs of parentheses, build the expressions for each value separately.

    Correct: (Language="French" OR Language="German" OR Language="Japanese")

    Correct: (Language="French" OR Language="German" OR Language="Japanese") AND (Version="1.0")

    Correct: (Language="French" OR Language="German") AND (Language="Japanese")

    Incorrect: Language="French" OR Language="German" OR Language="Japanese"

  • Only use the OR operator between attribute-value pairs for an attribute. Do not use the AND operator.

    Correct: (Language="French" OR Language="German" OR Language="Japanese") AND (Version="1.0" OR Version="2.0")

    Incorrect: (Language="French" OR Language="German" AND Language="Japanese") AND (Version="1.0" OR Version="2.0")

  • When the NOT operator is used, ensure that it is placed before the opening parenthesis of an attribute‑value group.

    Correct: NOT (Language="French" OR Language="German" OR Language="Japanese") AND (Version="1.0" OR Version="2.0")

    Correct: (Language="French" OR Language="German" OR Language="Japanese") OR NOT (Platform="Windows")

    Incorrect: (NOT Language="French" OR Language="German" OR Language="Japanese") AND (Version="1.0" OR Version="2.0")

    Incorrect: (Language="French" OR Language="German" OR Language="Japanese") OR (Platform="Windows" NOT Platform="UNIX")

  • If you have multiple attributes in a filter, insert the Boolean operator between two groups of attribute‑value pairs.

    Correct: (Language="French" OR Language="German") AND (Platform="Windows" OR Platform="UNIX")

    Incorrect: (Language="French" OR Language="German") (Platform="Windows" OR Platform="UNIX")

Process a filter

FrameMaker generates customized output of a structured document after processing the filter you applied to the document.

Consider a scenario in which you want the following elements and attributes to be applied to the various paragraphs in a structured document.

Paragraph

Element

Attribute

Value assigned

Paragraph 1

TextContent1

Language

Japanese

Version

2.0

Platform

Windows

Paragraph 2

TextContent1

Language

Japanese

Version

2.0

Platform

UNIX

Paragraph 3

TextContent2

Language

Japanese

Version

2.0

Paragraph 4

TextContent2

Language

English

Version

1.0

Paragraph 5

SysReq

Platform

Windows

Paragraph 6

SysReq

Platform

UNIX

Paragraph 7

LegalContent

Copyright

Condensed

  1. Copy the Sample XML code, which is based on this scenario, to create an XML file with the elements, attributes, and attribute values (listed in the previous table).

  2. Open the XML file in FrameMaker. These elements, attributes, and attribute values appear in the Structure View window.

  3. Type text in the relevant elements.

    For example, type Japanese text relevant to version 2.0 on Windows in the TextContent1 element.

  4. Create the following filter to generate a Japanese document for the Windows platform:

    (Language="Japanese") AND (Platform="Windows")

How FrameMaker processes a filter

FrameMaker matches each attribute-value pair in the filter with every element in the document. The result of matching the attribute-value pair with an element is indicated by one of the following values:

True:
The attribute in the filter is an attribute of the element being matched, and the value in the filter matches the value of the attribute of the element.

False:
The attribute in the filter is an attribute of the element being matched, but the value in the filter does not match the value of the attribute of the element.

Don’t-Care:
The attribute in the filter is not an attribute of the element being matched.

The following table demonstrates how the filter is processed:

(Language="Japanese") AND (Platform="Windows")

Paragraph

Element

Attribute

Value assigned

Verification of element based on the filter

Result

Paragraph 1

TextContent1

Language

Japanese

Is Language=Japanese?

Is Platform = Windows?

True

True

Version

2.0

Platform

Windows

Paragraph 2

TextContent1

Language

Japanese

Is Language=Japanese?

Is Platform = Windows?

True

False

Version

2.0

Platform

UNIX

Paragraph 3

TextContent2

Language

Japanese

Is Language=Japanese?

Is Platform = Windows?

True

Don’t-Care

Version

2.0

Paragraph 4

TextContent2

Language

English

Is Language=Japanese?

Is Platform = Windows?

False

Don’t-Care

Version

1.0

Paragraph 5

SysReq

Platform

Windows

Is Language=Japanese?

Is Platform = Windows?

Don’t-Care

True

Paragraph 6

SysReq

Platform

UNIX

Is Language=Japanese?

Is Platform = Windows?

Don’t-Care

False

Paragraph 7

LegalContent

Copyright

Condensed

Is Language=Japanese?

Is Platform = Windows?

Don’t-Care

Don’t-Care

Based on the results of filter processing as listed in this table, and the rules used to process filters, FrameMaker computes the final value of the filter to determine whether to include or exclude elements from the output. The overall computation returns one of the following values:

True (or) Don’t-Care:
The element is included in the output.

False:
The element is excluded from the output.

The operator precedence that FrameMaker uses while processing filters is listed in the descending order of precedence:

  1. Parenthesis

  2. NOT

  3. AND

  4. OR

Additional filter processing in the example

For element TextContent1 in Paragraph 1, the filter is processed as follows:

  1. The attribute-value pair Language="Japanese" evaluates to True and the attribute-value pair Platform="Windows" evaluates to True.

  2. The result of computing the filter is True and True, and the final computation of the element based on the rules is True. Hence, Paragraph 1 is included in the output.

The following table demonstrates how the entire document is filtered:

Paragraph

Element

Attribute-value pair matching against each element

Result based on the rules

Action

Paragraph 1

TextContent1

Is Language=Japanese?

True

True AND True=True

Include in output

 

 

Is Platform=Windows?

True

 

 

Paragraph 2

TextContent1

Is Language=Japanese?

True

True AND False=False

Exclude from output

 

 

Is Platform=Windows?

False

 

 

Paragraph 3

TextContent2

Is Language=Japanese?

True

True AND Don’t- Care=True

Include in output

 

 

Is Platform=Windows?

Don’t-Care

 

 

Paragraph 4

TextContent2

Is Language=Japanese?

False

False AND Don’t-Care=False

Exclude from output

 

 

Is Platform=Windows?

Don’t-Care

 

 

Paragraph 5

SysReq

Is Language=Japanese?

Don’t-Care

Don’t-Care AND True=True

Include in output

 

 

Is Platform=Windows?

True

 

 

Paragraph 6

SysReq

Is Language=Japanese?

Don’t-Care

Don’t-Care AND False=False

Exclude from output

 

 

Is Platform=Windows?

False

 

 

Paragraph 7

LegalContent

Is Language=Japanese?

Don’t-Care

Don’t-Care AND Don’t-Care=Don’t-Care

Include in output

 

 

Is Platform=Windows?

Don’t-Care

 

 

Paragraphs 1, 3, 5, and 7 are included in the output, based on the rules used to process filters.

Note: When an element is included in the output, the inclusion or exclusion of each of its child elements is determined by processing each child element. However, when a parent element does not satisfy the filter and is excluded from the output, its child element is also excluded from the output even if the child element satisfies the filter. In addition, FrameMaker does not process the root element while running the filter. Hence, the root element is always included in the output.

Rules used to process filters

The following table lists the rules that FrameMaker uses for processing filters.

Rule Description

Operator/Resultant Value

<Don't-care> OR <Don't-Care>

<Don't-Care>

<Don't-care> OR <True>

<True>

<Don't-care> OR <False>

<False>

<True> OR <Don't-care>

<True>

<False> OR <Don't-care>

<False>

<Don't-care> AND <Don't-Care>

<Don't-Care>

<Don't-care> AND <True>

<True>

<Don't-care> AND <False>

<False>

<True> AND <Don't-care>

<True>

<False> AND <Don't-care>

<False>

NOT <Don't-care>

<Don't-care>

<True> OR <True>

<True>

<False> OR <True>

<True>

<True> OR <False>

<True>

<False> OR <False>

<False>

<True> AND <True>

<True>

<False> AND <True>

<False>

<True> AND <False>

<False>

<False> AND <False>

<False>

NOT <True>

<False>

NOT <False>

<True>

Sample XML code

Copy the following code to a FrameMaker document, and then save it as an XML file.

    <?xml version="1.0" encoding="UTF-8" ?> 
    <Doc>  
        <Para>  
            <TextContent1 Language="Japanese" Version="2.0" Platform="Windows">TextContent1  
            with Language="Japanese" Version="2.0" Platform="Windows"</TextContent1>  
            </Para>  
        <Para>  
            <TextContent1 Language="Japanese" Version="2.0" Platform="UNIX">TextContent1 
            with Language="Japanese" Version="2.0" Platform="UNIX"</TextContent1>  
            </Para>  
        <Para>  
            <TextContent2 Language="Japanese" Version="2.0">TextContent2 with 
            Languaue="Japanese" Version="2.0"</TextContent2>  
            </Para>  
        <Para>  
            <TextContent2 Language="English" Version="1.0">TextContent2with 
            Language="English" Version="1.0"</TextContent2>  
            </Para>  
        <Para>  
            <Sysreq Platform="Windows">Sysreq with Platform="Windows"</Sysreq>  
            </Para>  
        <Para>  
            <Sysreq Platform="UNIX">Sysreq with Platform="UNIX"</Sysreq>  
            </Para>  
        <Para>  
            <LegalContent Copyright="Condensed">LegalContent with 
            Copyright="Condensed"</LegalContent>  
            </Para>  
        </Doc>

Import filters

You can import the Filter By Attribute settings that you defined in a structured document to other structured documents. The properties of the filter include the following:

  • Filter expressions. The filter expressions that you created in the source document.

  • Attribute values that are defined in the filter. Each attribute can be more than one values.

  • The Show Per Expression state. For example, if your source document has many filters defined, but when these filters are imported to target documents, the first filter is chosen for Show Per Expression, the same settings are applied to the target documents.

When you import filters, the attribute values in the source documents are added to the attribute values in the target documents. If attributes in the target documents already have some values, the imported values are appended to them. FrameMaker reports an error if the target documents do not have attributes present in the filter expressions in the source document.

  1. On the document window, select File > Import > Formats.

  2. On the Import Settings dialog box, deselect all options, and then select Filter By Attribute.

  3. In the Import From Document pop-up menu, select the source document that is open.

  4. Click Import.

Apply a filter

Use the following instructions to apply a filter you have created to your structured document.

  1. Select Special > Filter By Attribute. The Manage Attribute Expressions dialog box appears.

  2. Select Show As Per Expression to preview the elements that satisfy the filter when it is applied to the document.

    Note: If you select the Show All option, then the active filter, if any, is disabled, and all elements in the document are available for viewing and editing in FrameMaker. Also, any conditional text that is hidden appears. You can’t undo the Show All operation.
  3. Select a filter in the list.

  4. In the Filtered Text option, select how the content that does not meet the filter conditions should be treated. You can choose from the following:

    • Hide the content that is filtered out

    • Preview the filtered out content with a specified color.

    • Apply a condition tag to the filtered out content. In addition, you can also remove any condition tag already applied to the filtered out content.

  5. Click Apply.

    Note: You can’t undo the Apply command after applying a filter.

Save a document after applying a filter

When you save a document as a FrameMaker or MIF file, all filters using attribute values, including the filter you have applied to the document, are saved. The attribute values you have defined for this feature are also saved.

Note: When you save a document in the XML format, all filters using attribute values, are saved. However, the attribute values you have defined for this feature aren’t saved.

Modify a filter

Use the following steps to modify a filter:

  1. Select Special > Filter By Attribute. The Manage Attribute Expressions dialog box appears.

  2. Select a filter from the list.

  3. Click Edit. The Build Expression dialog box appears.

  4. Modify the filter in the Expression area.

  5. Click OK to close the Build Expression dialog box.

The modified content of the filter appears in the Selected Expression area of the Manage Attribute Expressions dialog box.

Delete a filter

Use the following steps to delete a filter:

  1. Select Special > Filter By Attribute. The Manage Attribute Expressions dialog box appears.

  2. Select a filter in the list.

  3. Click Delete.

  4. If the filter you are deleting has been applied to the document, FrameMaker displays a message indicating that the selected expression is currently applied to the document. Click OK.

  5. Click OK to confirm the deletion.

  6. Click Done to close the Manage Attribute Expressions dialog box.

Note: When you delete an active filter in a document, all elements that were excluded by the filter are again made available for viewing, editing, or generating output.

Disable applying condition tags to filtered content

You can disable the option of applying a condition tag to content filtered with a Filter By Attribute option.

 Set ApplyAsCondition=Off in the maker.ini file.
Note: Use caution when editing an ini file.