Dynamic Query Component

This feature is available since Bloomreach Experience Manager 14.3.0

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 the Base 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 named documentTypes. Beans from that query will be set in the request model, contained in a Pagination object with name pagination.

Apart from the query results, the pagination object also contains everything needed for a front-end consumer of the Delivery 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.

Comma separated list of document type names. This triggers a search for documents of that type.

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"
  }
It's important to note the distinction between the top level object "page", which stands for the webpage that has been requested from the Delivery 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

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 the DocumentQueryDynamicComponent 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"
      }
    }
  }
}
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?