Documentation Center

Building a Custom Search Query

XQuery is a powerful language for querying XML. You can customize the XQuery code included in your skin to build a specialized search query, providing you with more specific types of queries than can be achieved through simple search categories.

About this task

ContentDelivery_home refers to ContentDelivery_InstallDir\WEB-INF on Windows and ContentDelivery_InstallDir/WEB-INF on Linux.

Procedure

  1. The Legacy Content Delivery base skin provides example custom queries in its XQuery. Copy the search_query.xql file from ContentDelivery_home/db/LiveContent/ui/skins/base/xql/ into the same location within your skin.
  2. Examine the comments in the file search_query.xql thoroughly, as they note what variables are available and the required output of the query. The search_query.xql XQuery is executed if a scope parameter is provided to the search API that starts with the key phrase custom:. For example, if a scope of custom:draft-comments was provided, the search API would execute the code within search_query.xql.
  3. As a developer, your goal within this XQuery is to return a list of XPath evaluators as a string. This list of XPath evaluators should allow you to select the topics for which your end-user is attempting to search. For example, the evaluator "[descendant::draft-comment]" will cause the search engine to seek out of any XML topics within the scope of the search that contain a draft-comment element.
  4. Add a new if-else to the query which matches against your custom scope. Use XQuery code as needed to extend the query to match your custom requirements.

    In this example, the query triggered by a scope equal to custom:recent-topics will execute a full text search against the repository for any topics that have been modified in the last seven days.

    
    ...
    ) else if($scope = "custom:recent-topics") then (
       
       (: we are interested only in searching for documents that have changed in the last 7 days :)
       let $duration := "P7D"
         
       (: get the current date, and then subtract 7 days :)
       let $date := current-date()
       let $before := $date - xs:dayTimeDuration($duration)
       return
    
       (: 
    
       1. We return a string, with all the variables interpolated.  
          Unless a variable is in the list in the comments within this file,
          it has to be concatenated into the string as its value, because the variable 
          will not be available when this query is finally run.
    
       2. Note the second evaluator on the query.  This is the basic full text query,
          which goes after the time-check. Remember that we are looking for topics modified 
          within the last seven days AND those that contain our normal text query.
    
       :)
    
       concat("[@modified_date > '", $before, "'][ft:query(., $fquery)]")
    ) ... 
    
  5. In order to use this new search query type, you must execute the search API with a scope equal to custom:recent-topics. This will require additional skin modification to add this capability to your user interface. For example, you may need to add additional language items to give a localized name to your new search categories ("Draft Comments"). In addition, you need to expose this new search category through the user interface, either through a button, or an option on the advanced search page HTML template (advanced_search.html).
  6. Upload the new skin customization into the database.
    • You can upload the resources using the web UI, as described by Adding a Skin and Resources.
    • You can also update the skins via the command line using the loaddb tool. Copy the updated skin resources from the source code repository to ContentDelivery_home/db/LiveContent/ui/skins/<your_skin>/.
      • On Windows, to load the most recent changes into the database run this command:

        loaddb.bat UPGRADE

      • On Linux, run this command:

        loaddb.sh UPGRADE