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:

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-engine.js.
4. 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.
5. Implement your search engine.
6. In the fragments folder, create a file named search-engine-script-fragment.xml.
7. 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>

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 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>