Replacing the Search Engine Only

It is possible to replace the internal search engine that is used by Oxygen XML WebHelp by using a custom JavaScript file. This customization method allows you to replace the search engine but keep the search results presentation.

To replace WebHelp's internal search engine, follow this procedure:

If you have not already created a Publishing Template, see How to Create a Publishing Template.
Create the following items in the folder that contains your publishing descriptor file (the .opt file):
- A folder named js.
- A folder named fragments.
In the js folder, create a file named search-engine.js.

As a starting point, you can copy the following content to the search-engine.js file:

/**
 * Object that implements the methods required by WebHelp to run a search engine.
 */
function CustomSearchEngine() {
     
  /**
   * Method required to run the search engine in webhelp. Handler when the users 
   * executes the query in the search page. 
   * 
   * @param {String} query            The search input string from the user.
   * @param {Function} successHandler Needs to be called if the search operation is executed
   *                                  successfully. The parameter needs to have the type of 
   *                                  WebHelpAPI.SearchResult
   * @param {Function} errorHandler   Needs to be called if the search operation fails to
   *                                  execute successfully. It needs to have the type 
   *                                  of String. 
   */
  this.performSearchOperation = function(query, successHandler, errorHandler) {
      // implement search engine
      // const searchRestult = externalSearchEngine(query);

      // convert the result to WebHelpApi.SearchResult
      // const formattedResult = convert(searchRestult);

      // call successHanlder with the converted result.
      // successHandler(formattedResult)  
  }

  /**
   * Method required to run the search engine in webhelp. Handler when the 
   * page is changed in the search page.
   * 
   * @param {Integer} pageToShow      The page to be dispalyed.
   * @param {Integer} maxItemsPerPage The maximum # of items that can be displayed on a page.
   * @param {String} query            The search input string from the user.
   * @param {Function} successHandler Needs to be called if the search operation is executed
   *                                  successfully. The parameter needs to have the type of
   *                                  WebHelpAPI.SearchResult 
   * @param {Function} errorHandler   Needs to be called if the search operation fails to
   *                                  execute successfully. It needs to have the type 
   *                                  of String.  
   */
  this.onPageChangedHandler = function(pageToShow, maxItemsPerPage, query, successHandler, 
errorHandler) {
      // implement search engine
      // const searchRestult = externalSearchEngine(pageToShot, maxItemsPerPage, query);

      // convert the result to WebHelpApi.SearchResult
      // const formattedResult = convert(searchRestult);

      // call successHanlder with the converted result.
      // successHandler(formattedResult)  
  }
}

// Set the Search Engine to WebHelp
WebHelpAPI.setCustomSearchEngine(new CustomSearchEngine());

Note: See the API Search Objects section for details on how to convert your custom search engine results to WebHelpAPI.SearchResult.

Implement your search engine.
In the fragments folder, create a file named search-engine-script-fragment.xml.
In the search-engine-script-fragment.xml file, define the scripts that are required for your search engine to run. For example:
```
<div>
    <script src="${oxygen-webhelp-template-dir}/js/search-engine.js"></script>
</div>
```
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>
```

Set the transformation parameters needed to enable the search filter. For this, open the .opt file and add the following content inside the <webhelp> element:

<html-fragments>
  <fragment file="fragments/search-engine-script-fragment.xml" 
      placeholder="webhelp.fragment.head.search.page"/>
</html-fragments>

API Search Objects

To replace the WebHelp Search Engine, you will need to convert your custom search result into WebHelp API Objects that WebHelp will use to render your search result on the search page. To convert your custom search result, you will have to create the following objects:

WebHelpAPI.SearchMeta is a JavaScript object used to hold additional information for the search result. To create such an object, the following fields are required:
- String: searchEngineName - The name of the search engine used to retrieve the search result.
- Integer: totalSearchItems - The total number of search items the search engine returned.
- Integer: currentPage - The current page to display.
- Integer: maxItemsPerPage - The maximum number of items that can be displayed on a page.
- Integer: totalPages - The number of total pages for the search result.
- String: originalSearchExpression - The query string the user typed in the search input field.
```
conse searchMeta = new WebHelpAPI.SearchMeta(searchEngineName, totalSearchItems, currentPage, 
maxItemsPerPage, totalPages, origianlSearchExpresion);
```
WebHelpAPI.SearchDocument is a JavaScript object used to hold the search result for a single topic/HTML page. To create such an object, the following fields are required:
- String: linkLocation - The URL to the topic.
- String: title - The topic title.
- String: shortDescription - The topic short description.
```
const searchDocument = new WebHelpAPI.SearchDocument(linkLocation, title, shortDescription);
```
WebHelpAPI.SearchResult is a JavaScript object used to display the search results in the search page. To create such an object, the following fields are required:
- WebHelpAPI.SearchMeta: searchMeta - Contains additional information for the search result.
- Array[WebHelpAPI.SearchDocument]: documents - An array with the matching documents (HTML pages) for the search result.
```
conse searchMeta = new WebHelpAPI.SearchMeta(searchEngineName, totalSearchItems, currentPage, 
maxItemsPerPage, totalPages, origianlSearchExpresion);
const searchDocument = new WebHelpAPI.SearchDocument(linkLocation, title, shortDescription);
const documents = [searchDocument]; // An array with one element.
const searchResult = new WebHelpAPI.SearchResult(searchMeta, documents);
```