Creating and Registering Filters
Filters can help readers narrow the scope of the information that is presented, making it easier to find desired topics. Each filter is based on an attribute that has been defined in the attribute definition (.HxA) file and added to the XML data island of selected topics.
Procedure
To create and register a set of Help filters
Ensure that attributes are properly defined in the attribute definition (.HxA) file for the project. For details, see Attribute Definition (.Hxa) File.
Ensure that the each topic contains the appropriate attribute markup. Attribute markup is part of the XML data island for each topic.
Define the filters for the collection. Each filter should contain the following information:
A unique identifier. This is used only by the installer, and does not appear to the customer.
A description. This is the friendly name for the filter that is displayed to users.
A filter string. This is the query syntax that makes the filter work. It is the most critical part of the filter. Each filter string contains the name and one value for the attribute being filtered. The syntax for a filter string is as follows:
"Product" = "Access"When applied, a filter that contains this string would exclude all topics not containing the "Access" value of the "Product" attribute.
Add this information to MSHelp2_RegTables__RTL_---_---.msm. The following table lists the columns in that need to be updated with information for each filter that has been defined for your project.
Data table
Column
Value to enter
HelpFilter
FilterKey
Unique identifier for the filter.
HelpFilter
Description
Description text for the filter.
HelpFilter
QueryString
The filter string.
Filter String Syntax
The filter string defines the behavior of each filter that is defined for a Help collection. Filter strings are constructed by joining attribute names and values together using logical operators. Parentheses can be used for grouping operations.
The following operators are permitted:
=
AND
OR
NOT
()
The following examples demonstrate several possible ways to construct a filter string:
This simple filter string consists of a single attribute name and value.
"DevLang" = "C++"The filter string in the previous example can be expanded upon by adding the NOT operator.
"DevLang" = "C++" NOT "Technology" = "MFC"This filter string uses parentheses for a more complex string.
"DevLang" = "VisualBasic" AND ("Technology" = "ActiveX" OR "Technology" = "COM")Parentheses are used to create a grouped statement.
"Level" = "Expert" AND (("TopicType" = "Reference" OR "TopicType" = "Procedure") AND ("DevLang" = "C++" OR "DevLang" = "C#")) NOT "Technology" = "Database"
Attributes are defined for a collection at authoring time. To be effective, any filter that is created must reference valid attribute data. Thus, if you hard-code attribute data in your filter code, it is a good idea to verify it against your Help content.
See Also
Concepts
Attribute Definition (.Hxa) File