Base query component

Component ID

The base query component is defined in the base component group by the ID:

base/query

Purpose

This component provides all of the functionality of the Base component and extends it to handle common use cases related to document queries and listing. The component will perform a query if it finds a parameter named documentTypes. Content items from that query will be included in the Delivery API's Pages endpoint response, contained in a pagination object.

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	Type	Default value	Description
*	(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.
documentTypes	string	-	Required, otherwise component defaults to Base Component behavior. Comma separated list of document type names. This triggers a search for documents of that type.
scope	contentpath	-	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
includeSubtypes	boolean	false	Whether to include subtypes of the specified documentTypes in the search
sortField	string	-	A document field to sort on (optional). When not specified, results will be sorted on their internal query result score.
sortOrder	dropdown	DESC	Sort order enum (ASC,DESC)
pageSize	int	10	Maximum number of documents to be rendered in the Page Model API per request
dateField	string	-	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
hideFutureItems	boolean	false	If set, a date filter is added to the query, that filters out items whose dateField property is greater than the current (runtime) date
hidePastItems	boolean	false	If set, a date filter is added to the query, that filters out items whose dateField property is less than the current (runtime) date

Component request parameters

The component accepts the following (component-namespaced, i.e. {componentId}:{parameterName}) request parameters upon calling it:


Name	Type	Default value	Description
page	int	1	This parameter allows requesting a specific page, when the response is paginated. Example: `r3_r1_r1:page=1`
limit	int	10	Given 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 "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: /news?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	Type	Description
items	array	Actual data for the items contained in the current page.
size	int	Number of items listed on the current page.
offset	int	The offset value which the result set should start from.
total	int	Total number of items.
first	Page	First page of the paginator.
previous	Page	Previous page of the paginator.
current	Page	Current page of the paginator.
next	Page	Next page of the paginator.
last	Page	Last page of the paginator.
pages	array	Currently listed pages on the paginator.
enabled	boolean	Whether the pagination is enabled.

Page attributes


Attribute	Type	Description
number	int	Page number.
site	link	Internal link of the page.
self	link	External link of the page.

Below you can see how the DocumentQueryDynamicComponent renders in the JSON response from the Delivery API's Pages endpoint, along with the pagination object. The search results have been omitted from this example for brevity.

{
  "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"
        }
      }
    },
    ...
    "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
    },
    ...
  }
}

Component ID

Purpose

Component parameters

Component request parameters

Pagination attributes

👍Tip

Page attributes

👍
Tip