Edit online

How to Implement a Custom Search Filter

It is possible to implement a custom search filter (search input component) in your WebHelp Responsive output. The search input component is where users enter search queries to locate certain content within the WebHelp output.

To integrate a custom search filter, follow these steps:
  1. If you have not already created a Publishing Template, see How to Create a Publishing Template.
  2. Create the following items in the folder that contains your publishing descriptor file (the .opt file):
    • A folder named js.
    • A folder named fragments.
  3. In the js folder, create a file named search-filter.js.
  4. As a starting point, you can copy the following content to the search-filter.js file:
    /**
     * Object that implements the methods required by WebHelp to run a search filter.
     */
    function CustomSearchFilter() {
    
        /**
         * Method required to run the search filter in webhelp. It is called when the users 
         * executes the query in the search page. 
         * 
         * @param {WebHelpAPI.SearchResult} searchResult The search result for the executed query.
         *
         * @return A list of WebHelpAPI.SearchResult objects
         */
        this.filterResults = function (searchResult) {
            // implement filter
            return filteredResults;
        }
    }
    
    // Set the Search Filter to WebHelp
    WebHelpAPI.setCustomSearchFilter(new CustomSearchFilter());
    ...
    Note: See the API Search Objects section for details on how to create a WebHelpAPI.SearchResult object.
  5. Implement your custom search filter.
  6. In the fragments folder, create a file named search-filter-script-fragment.xml.
  7. In the search-filter-script-fragment.xml file, define the scripts that are required for your custom search filter to run. For example:
    <div>
        <script src="${oxygen-webhelp-template-dir}/js/search-filter.js"></script>
    </div>
  8. Copy the js folder to the output folder during the transformation process. For this, open the .opt file and add the following content in the <resources> section (see Template Resources for more details):
    <fileset>
      <include name="js/**"/>
    </fileset>
  9. Set the transformation parameters needed to enable the custom search filter. For this, open the .opt file and add the following content inside the <webhelp> element:
    <html-fragments>
      <fragment file="fragments/search-filter-script-fragment.xml" 
          placeholder="webhelp.fragment.head.search.page"/>
    </html-fragments>
  10. Run the transformation with this publishing template selected.