Share via

Managing Help Filters

  • Article

Filters help end users narrow the scope of the information that is presented, making it easier to find desired topics. Each documentation set in the Visual Studio Combined Collection has a number of 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 Help collection's installer (.MSM or .MSI) file. (For information about how to create an installer for your Help collection, see Walkthrough: Registering and Integrating a Help Collection By Using Windows Installer.) Filters are registered alongside the Help collection during setup. For more information about Help filters, see Creating and Registering Filters in the Help Authoring.

At a minimum, it is recommended that each topic contain attribute keywords that will allow 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.

Note

The following procedure uses a merge module editing utility called 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" in the MSDN Library to locate the latest download of the Windows Installer SDK.

How to Create and Register a Help Filter

To create and register a Help filter for a Help collection

  1. Ensure that attributes are properly defined in the attribute definition (.HxA) file and that each topic contains the appropriate attribute markup.

  2. Define a filter for the collection, such as "DocSet"="HelpDemo".

    When applied, this filter will exclude all topics that do not contain the "HelpDemo" value of the "DocSet" attribute.

  3. Open the Help collection's installer (.MSM or .MSI) file by using the Orca utility.

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

    Column

    Data

    FilterKey

    helpdemo

    Description

    Help Demo Collection Filter

    QueryString

    "DocSet"="HelpDemo"

  5. Select the HelpFilterToNamespace table and add a new row for each filter, as shown in the following table. The HelpFilterToNamespace table maps the Help filters defined in the HelpFilter table to the Help namespace defined in the HelpNamespace table.

    Column

    Data

    HelpFilter_

    helpdemo

    HelpNamespace_

    MS.HelpDemo.1033

    The HelpFilter_ entry is obtained from the FilterKey column of the HelpFilter table. Find the HelpFilter entry.

    The HelpNamespace_ entry is obtained from the NamespaceKey column of the HelpNamespace table.

See Also

Concepts

Collection-Level .HxA File

Creating and Registering Filters

Other Resources

Getting Started with Help Content and Integration