Dynamic Query Component

Info: Available in brXM 14.3.0 and later.

Class Name

The Dynamic Query Component is implemented by the following class:

org.hippoecm.hst.component.support.bean.dynamic.DocumentQueryDynamicComponent

Overview

The DocumentQueryDynamicComponent extends the Base Dynamic Component to support document queries and result listing. When the component receives a documentTypes parameter, it executes a query for those document types. The resulting beans are added to the request model in a pagination object.

The pagination object includes both the query results and all metadata required for rendering pagination controls in a front-end application using the Delivery API. This includes links and labels for navigation (such as "previous", "next", "first", and "last" pages) under a child object called pages. See the JSON example below for details.

Component Parameters

The following parameters configure the component:

Name	Type	Default value	Description
*	(Any except JcrPath)	-	The parameter name and value are rendered via the Delivery API.
*	JcrPath	-	All parameters of this type are processed. The component looks up the referenced document by path and includes its content in the Delivery API. If the path does not reference a document, only the path is rendered.
documentTypes	string	-	Required. Comma-separated list of document type names. Triggers a search for documents of the specified types. If not set, the component behaves as the Base Dynamic Component.
scope	JcrPath	-	Defines the search scope. Only documents below this JCR path are included in results. Use a relative path from the site content root.
includeSubtypes	boolean	false	If true, includes subtypes of the specified documentTypes in the search.
sortField	string	hippostdpubwf:publicationDate	Field to sort by. Optional.
sortOrder	dropdown	ASC	Sort order: ASC or DESC.
pageSize	int	10	Maximum number of documents returned per request in the Delivery API.
dateField	string	-	Path to a date field in the queried document type(s). Used for date filtering with hideFutureItems or hidePastItems.
hideFutureItems	boolean	false	If true, filters out items where dateField is greater than the current date.
hidePastItems	boolean	false	If true, filters out items where dateField is less than the current date.

Component Request Parameters

The component accepts the following request parameters (component namespaced):

Name	Type	Default value	Description
page	int	1	Specifies the page number to request when results are paginated.
limit	int	10	Limits the number of pages included in the JSON output under the pages object. By default, all pages are included, which can result in large JSON responses. The limit parameter restricts the number of pages and adjusts "previous" and "next" entries relative to the current page.

Pagination Attributes

The component exposes search results through a pagination object in the Delivery API JSON output. The pagination object appears under the top-level page object and is referenced from the component's models object:

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

Note: The top-level page object represents the requested web page. The pages and pagination objects provide pagination data for the query component.

The pagination object includes the following attributes:

Attribute	Type	Description
offset	int	The starting offset of the result set.
items	array	Items included on the current page.
total	int	Total number of items matching the query.
first	Page	First page in the paginator.
previous	Page	Previous page in the paginator.
current	Page	Current page in the paginator.
next	Page	Next page in the paginator.
last	Page	Last page in the paginator.
pages	array	List of pages currently shown in the paginator.
size	int	Number of items on the current page.
enabled	boolean	Indicates if pagination is enabled.

Page Attributes

Each page object in the paginator includes:

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

Example JSON Output

Below is an example of the JSON response from the Delivery API for the DocumentQueryDynamicComponent. The search results are omitted for brevity. The structure for the scope parameter (of type JcrPath) is included.

{
  "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"
      }
    }
  }
}
copy