Edit online

How to Configure Faceted Search in WebHelp Output

A faceted search is a powerful tool that allows users to refine search results by selecting filters or facets. Facets are predefined categories that are associated with search results. By selecting one or more facets, users can narrow down their search results to a specific category or set of categories.

Configure Oxygen Feedback as an External Search Engine

To enable faceted searches, you need to have a search engine that supports this functionality. The Oxygen Feedback search engine implements faceted searches and can be easily configured as a search engine for WebHelp, see Adding Oxygen Feedback to WebHelp Responsive Documentation for more details.

Attention: The default search engine that comes embedded in the WebHelp Responsive output does not support faceted searches.

Defining Facets Using a DITA Subject Scheme Map

A subject scheme map can be used to define controlled values and subject definitions. Subject definitions are classifications and sub-classifications that compose a tree. Subject definitions provide semantics that can be used in conjunction with taxonomies and ontologies.

The <subjectdef> element is used to define both a subject category and a list of controlled values. The parent <subjectdef> element defines the category, and the children <subjectdef> elements define the controlled values.

The following example defines the "Operating system" category, with "Linux" and "Windows" sub-categories. The controlled values (facet values) are: "RedHat Linux", "SUSE Linux", "Windows 7", and "Windows 10".

<subjectScheme>
    ...
    <hasInstance>            
        <subjectdef keys="os" navtitle="Operating system">
            <subjectdef keys="linux" navtitle="Linux">
                <subjectdef keys="redhat" navtitle="RedHat Linux"/>
                <subjectdef keys="suse" navtitle="SUSE Linux"/>
            </subjectdef>
            <subjectdef keys="windows" navtitle="Windows">
                <subjectdef keys="win7" navtitle="Windows 7"/>
                <subjectdef keys="win10" navtitle="Windows 10"/>
            </subjectdef>    
        </subjectdef>
    </hasInstance>
    ...
</subjectScheme>

Associating Faceted Values With a Topic Using a DITA Classification Map

The classification domain provides elements that enable map authors to indicate information about the subject matter of DITA topics. The subjects are defined in subject scheme maps, and the subjects are referenced using the @keyref attribute.

The following example shows you how to associate a faceted value with a topic:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Classification Map//EN" "classifyMap.dtd">
<map>
    <title>Classification map</title>
    <topicref keyref="how-to-install-on-suse.dita">
      <topicsubject keyref="linux">
        <subjectref keyref="suse"/>
      </topicsubject>
    </topicref>
  
    <topicref keyref="how-to-install-win7.dita">
      <topicsubject keyref="windows">
        <subjectref keyref="win7"/>
      </topicsubject>
    </topicref>
</map>

Note: The facet information cascades into child <topicref> elements.

Refining the Search Results by Using Facets in the Search Page

The configured facets are displayed in the search page, allowing you to narrow down the results.

When a user selects a facet, the search results are updated to only include the topics that match the selected facets. If multiple facet values are selected from the same category/facet, the search results display all topics with at least one facet. On the other hand, if multiple facet values from distinct facets are selected, the search results display all topics with all selected facet values.