How to: Create and Register Help Filters

  • Article

Filters narrow the scope of the information that is presented, making it easier for users to find desired topics. Each documentation set in the Visual Studio Help collection has predefined filters that are registered along with the Help files.

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. Once a set of filters has been defined, data for each filter must be added to the MSHelp2_RegTables__RTL_---_---.msm file. Filters are registered with the Help collection during setup.

At a minimum, it is recommended that each topic contain attribute keywords that enable users to filter for the product with which the topics are associated. The XML data island in each topic must contain a keyword related to the product attribute, for example, <MSHelp:Attr Name = "Product" Value = "Access"/>. Of course, you can add as many filters as you like. The following procedure demonstrates how to add a filter to your Help collection.

Note

To complete this procedure, you need a merge module editing utility named Orca (Orca.exe), which is available as part of the Microsoft Windows Installer SDK. The Windows Installer SDK can be installed from the MSDN Download Center https://msdn.microsoft.com/downloads. Search for "Orca" on the site to locate the latest download of the Windows Installer SDK.

To create and register a Help filter

  1. Ensure that attributes are properly defined in the attribute definition (.HxA) file for your Microsoft Help Workshop project and that each topic contains the appropriate attribute markup.

  2. Define a filter for your Help collection, "DocSet"="HelpIntegrDemo".

    When applied, this filter will exclude all topics not containing the "HelpIntegrDemo" value of the "DocSet" attribute.

  3. Open MSHelp2_RegTables__RTL_---_---.msm by using the Orca utility.

  4. Select the HelpFilter and add a new row for each filter, as shown in the following table.

    Column

    Data

    FilterKey

    helpintegrdemo_product

    Description

    My Help Collection

    QueryString

    "DocSet"=" HelpIntegrDemo".

  5. Select the HelpFilterToNamespace table and add a new row for each filter. This table maps the Help filters defined in the HelpFilter table to the Help namespace defined in the HelpNamespace table.

    Column

    Data

    HelpFilter_

    <helpintegrdemo_product>

    HelpNamespace_

    <MS.MyHelp.1033>

    The HelpFilter_ entry is obtained from MSHelp2_RegTables__RTL_---_---.msm HelpFilter table. Find the HelpFilter entry. Copy the FilterKey column value and paste it into the HelpFilter_ column of the HelpFilterToNamespace table of MSHelp2_RegTables__RTL_---_---.msm.

    The HelpNamespace_ entry is obtained from the MSHelp2_RegTables__RTL_---_---.msm HelpNamespace table. Find the HelpNamespace entry for the namespace. Copy the NamespaceKey column value and paste it into the HelpNamespace_ column of the HelpFilterToNamespace table of MSHelp2_RegTables__RTL_---_---.msm.

See Also

Tasks

Walkthrough: Registering and Integrating a Help Collection By Using Windows Installer

Concepts

Collection-Level .HxA File

Creating and Registering Filters

Other Resources

Getting Started with Help Content and Integration