Dynamic Query Component
Class Name
The Dynamic Query Component is implemented by the class
org.hippoecm.hst.component.support.bean.dynamic.DocumentQueryDynamicComponent
Purpose
This class provides all of the functionality of theBase Dynamic 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 nameddocumentTypes. Beans from that query will be set in the request model, contained in a Pagination object with namepagination.
Apart from the query results, the pagination object also contains everything needed for a front-end consumer of theDelivery API, 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 in the Delivery API 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 JcrPath) | - | Parameter name and value will be rendered via the Delivery API |
* | JcrPath | - | This component will process all parameters of this type, lookup the referenced document by its path, and include its content in the Delivery API. 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 Dynamic Component behavior. |
scope | JcrPath | - | The scope for the search. Only documents below this JCR 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 | hippostdpubwf:publicationDate | A document field to sort on (optional) |
sortOrder | dropdown | ASC | Sort order enum (ASC,DESC) |
pageSize | int | 10 | Maximum number of documents to be rendered in the Delivery 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) 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 |
| 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. |
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" }Below you can see a description of the attributes of the pagination object.
Attribute | Type | Description |
offset | int | The offset value which the result set should start from. |
| items | array | Actual data for the items contained in the current page. |
| 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. |
| size | int | Number of items listed on the current page. |
| 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 theDocumentQueryDynamicComponent renders in the JSON response in Delivery API, along with the pagination object and the (JcrPath) 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" } } }}