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
Note: When Content Delivery is installed in a third-party web application server, ContentDelivery_home refers to ContentDelivery_InstallDir\WEB-INF (ContentDelivery_InstallDir/WEB-INF on Linux). When Content Delivery is installed with its bundled web application server, ContentDelivery_home refers to your installation directory, ContentDelivery_InstallDir.
Procedure
- The Content Delivery
baseskin 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. - 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
scopeparameter is provided to the search API that starts with the key phrasecustom:. For example, if a scope ofcustom:draft-commentswas provided, the search API would execute the code within search_query.xql.Note: You should never remove theelseblock in theif-elseblock in this query. If this block is removed, and your users attempt to search with an unmatchedscopeparameter, this will cause an extremely slow query to run which could cause performance degradation. - 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 adraft-commentelement. - Add a new
if-elseto 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
scopeequal tocustom:recent-topicswill 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)]") ) ... - In order to use this new search query type, you must execute the search API with a
scopeequal tocustom: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). - 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
- On Windows, to load the most recent changes into the database run this command: