Skip to content
  • Documentation >
  • Guide >
  • Content rendering >
  • Queries and controllers >
  • Content queries

Content queries

With content queries you can find and render specific content according to criteria that you define.

You can use queries to list or embed Content items, such as:

Content queries use the built-in Query controller which simplifies querying. For more complex cases, you can build custom controllers.

Query types

The Query controller offers a set of built-in Query types. You can use them in the content view configuration, or in the Content query Field.

You can also write custom Query types for the cases that are not covered by the built-in ones.

Query type configuration

To use a Query type, select the Query controller (ez_query) in the content view configuration and select the Query type under params.query.query_type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
folder:
    controller: ez_query::contentQueryAction
    template: '@ezdesign/full/folder.html.twig'
    params:
        query:
            query_type: 'Children'
            parameters:
                content: '@=content'
            assign_results_to: items
    match:
        Identifier\ContentType: folder

Use one of the following Query controller methods:

  • locationQueryAction runs a Location Search
  • contentQueryAction runs a content Search
  • contentInfoQueryAction runs a ContentInfo search
  • pagingQueryAction returns a PagerFanta object and can be used to quickly paginate query results

See the Search documentation page for more details about different types of search.

All Query types take the following parameters:

  • query_type is the name of the Query type to use.
  • parameters can include:
    • arbitrary values
    • expressions based on the content, location and view variables. For example, @=location.id is evaluated to the current Location's ID.
  • assign_results_to declares the Twig variable that contains the search results.

Tip

Search results are a SearchResult object, which contains SearchHit objects. To get the content or Locations that are in search results, you access the valueObject of the SearchHit.

Pagination

To paginate the results of a query, use the pagingQueryAction of the Query controller and assign a limit per page in params.query.limit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
            content_view:
                full:
                    folder:
                        controller: ez_query::pagingQueryAction
                        template: '@ezdesign/full/folder.html.twig'
                        params:
                            query:
                                query_type: 'Children'
                                parameters:
                                    content: '@=content'
                                assign_results_to: items
                                limit: 3
                        match:
                            Identifier\ContentType: folder

Use the pagerfanta function to render pagination controls:

1
2
3
4
5
6
7
8
{% for item in items %}
    {{ ez_render(item.valueObject) }}
{% endfor %}

{{ pagerfanta(items, 'ez', {
    'routeName': 'ez_urlalias',
    'routeParams': {'location': location }
}) }}

Content query Field

The Content query Field is a Field that defines a query. The results of the query are available in the Field value.

Content query Field definition

Query type

When adding the Field to a Content Type definition, select the Query type in the Query type dropdown. All Query types in the application are available, both built-in and custom ones.

Returned types

Select the Content Type of items you want to return in the Returned type dropdown. To take it into account, your Query type must filter on the Content Type. Provide the selected Content Type through the returnedType variable:

1
contentType: '@=returnedType'

Pagination

Select Enable pagination and set the number of items per page to paginate the results.

You can override the pagination settings from Field definition by setting the enablePagination, disablePagination or itemsPerPage parameters when rendering the Content query Field:

1
2
3
4
5
6
{{ ez_render_field(content, 'query', {
    location: location|default(null), 'parameters': {
        'enablePagination': true,
        'itemsPerPage': 8
    }
}) }}

You can also define an offset for the results. Provide the offset in the Query type, or in parameters:

1
offset: 3

If pagination is disabled and an offset value is defined, the query's offset is added to the offset calculated for a page. For example, with offset 5 and itemsPerPage 10, the first page starts with 5, the second page starts with 15, and so on.

Without offset defined, pagination defines the starting number for each page. For example, with itemsPerPage 10, first page starts with 0, second page starts with 10, and so on.

Parameters

The following variables are available in parameter expressions:

  • returnedType - the identifier of the Content Type selected in the Returned type dropdown
  • content - the current Content item
  • location - the current Location of the Content item
  • mainLocation - the main Location of the Content item
  • contentInfo - the current Content item's ContentInfo

Content view configuration

To render a Content query Field, in the content view configuration, use the content_query_field view type:

1
2
3
4
5
6
7
            content_view:
                content_query_field:
                    blog:
                        template: '@ezdesign/content_query/blog_posts.html.twig'
                        match:
                            Identifier\ContentType: blog
                            '@EzSystems\EzPlatformQueryFieldType\eZ\ContentView\FieldDefinitionIdentifierMatcher': query

The identifier of the Content query Field must be matched by using the '@EzSystems\EzPlatformQueryFieldType\eZ\ContentView\FieldDefinitionIdentifierMatcher' matcher.

Query results are provided to the template in the items variable. See List content for an example of using the Content query Field.