Text search results component

Component ID

The text search results component is defined in the base component group by the ID:

base/text-search-results

Purpose

This component provides all of the functionality of the Base component and extends it to handle common use cases related to listing search results for a free-text search by a site visitor. This component is typically combined with a separate component to render a search box on the site, which then triggers a new Delivery API request to render results with this component.

This component will perform a query based on the component parameters (component configuration) and the search term (request parameter). Content items retrieved from that query will be included in the Delivery API's Pages endpoint response, contained in a pagination object.

Note that this component is similar to the Content List component, except for two additional component configuration parameters 'searchTermRequestParameter' and 'searchFields', and an additional request parameter matching the value of 'searchTermRequestParameter'.

In addition, if the request parameter containing the search term is not provided, a message indicating that the search term is missing is returned instead of the pagination object, so the frontend application can react in a different way to this situation. This behavior is distinct from the Content List component.

Apart from the query results, the pagination object also contains everything needed for a front-end consumer of the Delivery API's Pages endpoint, to be able to render the pagination index usually shown below search results. Typically, this is the horizontal list of numbers in ascending order, denoting the different pages with results. The pagination output of the Delivery API's Pages endpoint provides all links, labels, and other useful objects (e.g. entries for "previous"/"first" and "next"/"last" pages) needed for rendering this list. This information is under the child object of the pagination object, called "pages". For an example, see the JSON example later in this document.

Component parameters

Name TypeDefault valueDescription
-(Any other than contentpath)-Parameter name and value will be rendered via the Delivery API's Pages endpoint.
-contentpath-This component will process all parameters of this type, lookup the referenced document by its path, and include its content in the Delivery API Pages endpoint response. If the path references any node other than a document, only the path itself will be rendered.
documentTypesstring-If empty, any document type can be retrieved

Comma separated list of document type names. This triggers a search for documents of that type.
scopecontentpath-The scope for the search. Only documents below this content path will be rendered in results. A relative path is expected as value for this parameter, relative to the site content root
sortFieldstringhippostdpubwf:publicationDateA document field to sort on (optional)
sortOrderdropdownASCSort order enum (ASC,DESC)
pageSizeint10Maximum number of documents to be rendered in the Page Model API per request
dateFieldstring-Path of a date field in the document type(s) used in the query. The value of this field is used in a date filter, when ‘hideFutureItems’ or ‘hidePastItems’ parameters are set
hideFutureItemsbooleanfalseIf set, a date filter is added to the query, that filters out items whose dateField property is greater than the current (runtime) date
hidePastItemsbooleanfalseIf set, a date filter is added to the query, that filters out items whose dateField property is less than the current (runtime) date
searchTermRequestParameterstringqName of the request query parameter used to send the site visitor's search terms in a Delivery API request
searchFieldsstring-A comma-separated list of fields where the search term should be looked for.
If the list is empty, every field will be taken into account.
Fields must be namespaced.
Works with primitive fields and taxonomies, but doesn't work with field groups

Component request parameters

The component accepts the following request parameters upon calling it:

Name TypeDefault valueDescription
{searchTermRequestParameter}string-The search term to use when executing the query. The default name of this parameter is 'q' but it might be changed by updating the component parameter searchTermRequestParameter

Example: q=delivery
pageint1This component-namespaced (i.e. {componentId}:page) parameter allows requesting a specific page, when the response is paginated.

Example: r3_r1_r1:page=1
limitint10Given the total number of results and the number of results per page (parameter pageSize) a total number of available pages (pages of results) is calculated. By default, all these pages are exposed in the JSON output, under the object named "pages". Sometimes this produces a very big json output. 

The component-namespaced (i.e. {componentId}:limit) "limit" parameter allows limiting how many pages are included in the json output. The entries for the "previous" and "next" pages are adjusted relative to the current page number.

Example: r3_r1_r1:limit=2

URL example: /search?q=delivery&r3_r1_r1:page=1&r3_r1_r1:limit=2

Pagination attributes

As mentioned previously, this component exposes the search results inside a Pagination object, in the Delivery API JSON output. The pagination object appears as an entry directly under the top level object "page", and is referenced (json reference) from the component. The reference can be seen inside the "pagination" object, inside the "models" object:

"models": {
  "pagination": {
    "$ref": "/page/uid7"
  }

👍

Tip

It's important to note the distinction between the top-level object "page", which stands for the webpage that has been requested from the Page Model API, and the "pages" and pagination objects used to denote the pagination a query component supports.

Below you can see a description of the attributes of the pagination object.

Attribute TypeDescription
offsetintThe offset value which the result set should start from.
itemsarrayActual data for the items contained in the current page.
totalintTotal number of items.
firstPageFirst page of the paginator.
previousPagePrevious page of the paginator.
currentPageCurrent page of the paginator.
nextPageNext page of the paginator.
lastPageLast page of the paginator.
pagesarrayCurrently listed pages on the paginator.
sizeintNumber of items listed on the current page.
enabledbooleanWhether the pagination is enabled.

Page attributes

Attribute TypeDescription
numberintPage number.
sitelinkInternal link of the page.
selflinkExternal link of the page.

Below you can see how the DocumentQueryDynamicComponent renders in the JSON response of the Delivery API's Pages endpoint, along with the pagination object and the (contentpath) scope parameter. The search results have been omitted from this example for brevity, as they are very similar in structure to the entry for the document coupled to the scope parameter.

{
  "page": {
    "uid0": {...},
    "uid1": {...},
    ...
    "uid5": {
      "id": "r22_r1_r4",
      "links": {
        "self": {
          "href": "http://localhost/site/resourceapi?_hn:type=component-rendering&_hn:ref=r22_r1_r4",
          "type": "external"
        }
      },
      "meta": {
        "paramsInfo": {
          "scope": "contentforquery",
          "pageSize": 6,
          "sortField": "",
          "sortOrder": "ASC",
          "documentTypes": "examplet:doctypeforquery",
          "includeSubtypes": false,
          "dateField": "",
          "hidePastItems": false,
          "hideFutureItems": false
        },
        "params": {}
      },
      "name": "examplequerycomponent",
      "label": "Example Query component",
      "type": "container-item",
      "componentClass": "org.hippoecm.hst.component.support.bean.dynamic.DocumentQueryDynamicComponent",
      "models": {
        "pagination": {
          "$ref": "/page/uid7"
        },
        "scope": {
          "$ref": "/page/ud3262fe9c31c4cd19f1bfb4f65fe25e8"
        }
      }
    },
    ...
    "uid7": {
      "offset": 0,
      "items": [
        {
          "$ref": "/page/u7467739e33b84a35b6b31659eb90fc67"
        },
        {
          "$ref": "/page/u5b49b58f903d4a91823a1b00fbabbf66"
        },
        {
          "$ref": "/page/uc28bf4536f834377a2ab219e6f71e72c"
        },
        {
          "$ref": "/page/u3046c7d1d14c42e9b13aa96d3c1ba819"
        },
        {
          "$ref": "/page/u9decc66350a340c3820cd6feaf06bab3"
        },
        {
          "$ref": "/page/ud94d39a9badb45419bf65d23e10f0aa3"
        }
      ],
      "total": 58,
      "first": {
        "number": 1,
        "links": {
          "site": {
            "href": "?r22_r1_r4:page=1&r22_r1_r4:limit=3",
            "type": "internal"
          },
          "self": {
            "href": "http://localhost/site/resourceapi?r22_r1_r4:page=1&r22_r1_r4:limit=3",
            "type": "external"
          }
        }
      },
      "previous": null,
      "current": {
        "number": 1,
        "links": {
          "site": {
            "href": "?r22_r1_r4:page=1&r22_r1_r4:limit=3",
            "type": "internal"
          },
          "self": {
            "href": "http://localhost/site/resourceapi?r22_r1_r4:page=1&r22_r1_r4:limit=3",
            "type": "external"
          }
        }
      },
      "next": {
        "number": 2,
        "links": {
          "site": {
            "href": "?r22_r1_r4:page=2&r22_r1_r4:limit=3",
            "type": "internal"
          },
          "self": {
            "href": "http://localhost/site/resourceapi?r22_r1_r4:page=2&r22_r1_r4:limit=3",
            "type": "external"
          }
        }
      },
      "last": {
        "number": 10,
        "links": {
          "site": {
            "href": "?r22_r1_r4:page=10&r22_r1_r4:limit=3",
            "type": "internal"
          },
          "self": {
            "href": "http://localhost/site/resourceapi?r22_r1_r4:page=10&r22_r1_r4:limit=3",
            "type": "external"
          }
        }
      },
      "pages": [
        {
          "number": 1,
          "links": {
            "site": {
              "href": "?r22_r1_r4:page=1&r22_r1_r4:limit=3",
              "type": "internal"
            },
            "self": {
              "href": "http://localhost/site/resourceapi?r22_r1_r4:page=1&r22_r1_r4:limit=3",
              "type": "external"
            }
          }
        },
        {
          "number": 2,
          "links": {
            "site": {
              "href": "?r22_r1_r4:page=2&r22_r1_r4:limit=3",
              "type": "internal"
            },
            "self": {
              "href": "http://localhost/site/resourceapi?r22_r1_r4:page=2&r22_r1_r4:limit=3",
              "type": "external"
            }
          }
        },
        {
          "number": 3,
          "links": {
            "site": {
              "href": "?r22_r1_r4:page=3&r22_r1_r4:limit=3",
              "type": "internal"
            },
            "self": {
              "href": "http://localhost/site/resourceapi?r22_r1_r4:page=3&r22_r1_r4:limit=3",
              "type": "external"
            }
          }
        }
      ],
      "size": 6,
      "enabled": true
    },
    ...  
    "ud3262fe9c31c4cd19f1bfb4f65fe25e8": {
      "type": "folder",
      "links": {
        "site": {
          "href": "/genericdetail/contentforquery",
          "type": "internal"
        }
      },
      "meta": {},
      "data": {
        "name": "contentforquery",
        "displayName": "contentforquery",
        "documentSize": 236,
        "localeString": "en",
        "id": "d3262fe9-c31c-4cd1-9f1b-fb4f65fe25e8"
      }
    }
  }
}

Note that if the query search term is missing, instead of the aforementioned pagination object, the model will include the following message:

"models": {
  "message": "missing-search-term"
  }