I searched and searched Adobe's help after repeatedly seeing the error message from the Filter by Attribute's build expression dialog:
"Invalid Expression, Kindly refer to help for rules on building expression."
After wrestling with this feature for a while, I got it working. And, decided to provide the following help topic on it. Comments, feedback, and improvements are welcome.
Using the Special, Filter by Attribute Command
The Filter by Attribute dialog lets you define a build expression to filter DITA content based on element attribute values.
The first step to using this dialog is to define attribute values that you will use in your build expression.
Select an attribute from the attribute list.
Enter a value for that attribute and click on Add.
The attribute value appears in the Defined Values list. This list displays all of the defined values for the selected attribute.
After defining the attribute values for filtering, the next step is to define a build expression that filters content based on the values.
To define the expression, it is important to understand the operation of the radio buttons (Equals, Any, and Contains Only) and their related expression syntax.
If you define some product attribute values (OneFish_Product, TwoFish_Product, RedFish_Product, BlueFish_Product) and you define an audience attribute value (InternalUsageOnly_Audience), you could use the values and the radio buttons to build the following expression for a public document describing the OneFish product:
(product # "OneFish_Product") AND NOT (audience="InternalUsageOnly_Audience")
To create this expression, select the product attribute, select the Contains Only radio button, and click on Add. Delete the extra attribute values from the expression until you have just the value shown above. Next, click on the "AND" then "NOT" buttons to add this syntax to the expression. Finally, select the audience attribute, select the Equals radio button, and click on Add.
Note: Filtering operation is NOT dynamic. If you modify attribute values, the content filtering does not take effect until you re-apply the filter expression to the file.
Creating Build Expressions from DITAVAL Property Values
The Filter by Attribute feature becomes valuable when you use it to apply the same content filtering as is provided by a DITAVAL file
In the example (above) a number of attribute values are defined. A corresponding DITAVAL file containing these attributes could be:
<?xml version='1.0' encoding='utf-8'?>
<val>
<!-- includes public info for OneFish product -->
<prop att='product' val='OneFish_Product' action='include' />
<prop att='product' val='TwoFish_Product' action='exclude' />
<prop att='product' val='RedFish_Product' action='exclude' />
<prop att='product' val='BlueFish_Product' action='exclude' />
<prop att='audience' val='InternalUsageOnly_Audience' action='exclude' />
</val>
The include and exclude actions shown match the filtering operation of the build expression (include only product="OneFish_Product" and exclude audience="InternalUsageOnly_Audience").