diff --git a/docs/guide/content_rendering/images.html b/docs/guide/content_rendering/images.html
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/docs/guide/controllers.md b/docs/guide/controllers.md
index e41816b431..ae9b5e44dc 100644
--- a/docs/guide/controllers.md
+++ b/docs/guide/controllers.md
@@ -172,50 +172,139 @@ The Query controller makes it easy to retrieve content without writing custom PH
- List of Blog posts in a Blog
- List of Images in a Gallery
-### Usage example
+### Built-in Query Types
-This example assumes a "Blog" container that contains a set of "Blog post" items. The goal is, when viewing a Blog, to list the Blog posts it contains.
+You can make use of the following built-in Query Types for quick rendering:
-Four items are required:
+#### Children
-- a `LocationChildren` QueryType - It will generate a Query retrieving the children of a given Location id
-- a View template - It will render the Blog, and list the Blog posts it contains
-- a `content_view` configuration - It will instruct Platform, when viewing a Content item of type Blog, to use the Query Controller, the view template, and the `LocationChildren` QueryType. It will also map the id of the viewed Blog to the QueryType parameters, and set which Twig variable the results will be assigned to.
-- [service registration of the QueryType](#registering-the-querytype-into-the-service-container)
+The `Children` Query Type retrieves children of the given Location.
-#### The LocationChildren QueryType
+It takes `location` or `content` as parameters.
-QueryTypes are described in more detail in the [next section](#querytype-objects). In short, a QueryType can build a Query object, optionally based on a set of parameters. The following example will build a Query that retrieves the sub-items of a Location:
+``` yaml
+params:
+ query:
+ query_type: 'Children'
+ parameters:
+ content: '@=content'
+ assign_results_to: items
+```
-``` php
- new ParentLocationId($parameters['parentLocationId']),
- ]);
- }
+It takes `location` or `content` as parameters.
- public function getSupportedParameters()
- {
- return ['parentLocationId'];
- }
+``` yaml
+params:
+ query:
+ query_type: 'Siblings'
+ parameters:
+ content: '@=content'
+ assign_results_to: items
+```
- public static function getName()
- {
- return 'LocationChildren';
- }
-}
+#### Ancestors
+
+The `Ancestors` Query Type retrieves all ancestors (direct parents and their parents) of the provided Location.
+
+It takes `location` or `content` as parameters.
+
+``` yaml
+params:
+ query:
+ query_type: 'Ancestors'
+ parameters:
+ content: '@=content'
+ assign_results_to: items
```
+#### RelatedToContent
+
+The `RelatedToContent` Query Type retrieves content that is a reverse relation to the provided Content item.
+
+It takes `content` or `field` as obligatory parameters.
+`field` indicates the Relation or RelationList Field that contains the relations.
+
+``` yaml
+params:
+ query:
+ query_type: 'RelatedToContent'
+ parameters:
+ content: '@=content'
+ field: 'relations'
+ assign_results_to: items
+```
+
+#### GeoLocation
+
+The `GeoLocation` Query Type retrieves content by distance of the location provided in a MapLocation Field.
+
+It takes the following obligatory parameters:
+
+- `field` - MapLocation Field identifier
+- `distance` - distance to check for
+- `latitude` and `longitude` - coordinates of the location to check distance to
+- (optional) `operator` - operator to check value against, by default `<=`
+
+``` yaml
+params:
+ query:
+ query_type: 'GeoLocation'
+ parameters:
+ field: 'location'
+ distance: 200
+ latitude: '@=content.getFieldValue("location").latitude'
+ longitude: '@=content.getFieldValue("location").longitude'
+ operator: '<'
+ assign_results_to: items
+```
+
+#### General Query Type parameters
+
+All built-in Query Types take the following optional parameters:
+
+- `limit` - limit for number of search hits to return
+- `offset` - offset for search hits, used for paging the results
+- `sort` - sorting options
+- `filter` - additional query filters:
+ - `content_type` - return only results of given Content Types
+ - `visible_only` - return only visible results (default `true`)
+ - `siteaccess_aware` - return only results limited to current SiteAccess root (default `true`)
+
+For example:
+
+``` yaml
+params:
+ query:
+ query_type: 'Children'
+ parameters:
+ content: '@=content'
+ filter:
+ content_type: ['blog_post']
+ visible_only: false
+ limit: 5
+ offset: 2
+ sort: 'content_name asc, date_published desc'
+ assign_results_to: items
+```
+
+!!! note "Sorting order"
+
+ To provide sorting order to the `sort` parameter, use names of the Sort Clauses in
+ `eZ\Publish\API\Repository\Values\Content\Query\SortClause`.
+
+#### Using built-in Query Types
+
+This example assumes a "Blog" container that contains a set of "Blog post" items. The goal is, when viewing a Blog, to list the Blog posts it contains.
+
+Two items are required:
+
+- a View template - It will render the Blog, and list the Blog posts it contains
+- a `content_view` configuration - It will instruct Platform, when viewing a Content item of type Blog, to use the Query Controller, the view template, and the `Children` QueryType. It will also map the ID of the viewed Blog to the QueryType parameters, and set which Twig variable the results will be assigned to.
+
#### The `content_view` configuration
We now need a view configuration that matches Content items of type "Blog", and uses the QueryController to fetch the blog posts:
@@ -227,24 +316,24 @@ ezplatform:
content_view:
full:
blog:
- controller: ez_query:locationQueryAction
+ controller: ez_query:contentQueryAction
template: content/view/full/blog.html.twig
match:
Identifier\ContentType: "blog"
params:
query:
- query_type: LocationChildren
+ query_type: Children
parameters:
- parentLocationId: '@=location.id'
+ location: '@=location'
assign_results_to: blog_posts
```
-The view's controller action is set to the QueryController's `locationQuery` action (`ez_query:locationQueryAction`). Other actions are available that run a different type of search (contentInfo or content).
+The view's controller action is set to the QueryController's `contentQuery` action (`ez_query:contentQueryAction`). Other actions are available that run a different type of search (contentInfo or location).
The QueryController is configured in the `query` array, inside the `params` of the `content_view` block:
- `query_type` specifies the QueryType to use, based on its name.
-- `parameters` is a hash where parameters from the QueryType are set. Arbitrary values can be used, as well as properties from the currently viewed [Location](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Publish/API/Repository/Values/Content/Location.php) and [ContentInfo](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Publish/API/Repository/Values/Content/ContentInfo.php). In that case, the id of the currently viewed Location is mapped to the QueryType's `parentLocationId` parameter: `parentLocationId: "@=location.id"`
+- `parameters` is a hash where parameters from the QueryType are set. Arbitrary values can be used, as well as properties from the currently viewed [Location](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Publish/API/Repository/Values/Content/Location.php) and [ContentInfo](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Publish/API/Repository/Values/Content/ContentInfo.php). In that case, the ID of the currently viewed Location is mapped to the QueryType's `location` parameter: `location: '@=location'`
- `assign_results_to` sets which Twig variable the search results will be assigned to.
#### The view template
@@ -259,6 +348,71 @@ Results from the search are assigned to the `blog_posts` variable as a `SearchRe
{% endfor %}
```
+### Creating custom Query Types
+
+Beyond the built-in Query Types, you can create your own.
+
+For example, this Query Type returns a Query that searches for the last ten published Content items, ordered by reverse publishing date.
+It accepts an optional `type` parameter [lines 13-15] that can be set to a Content Type identifier (e.g. `article`):
+
+``` php
+ new Query\Criterion\LogicalAnd($criteria),
+ 'sortClauses' => [new Query\SortClause\DatePublished()],
+ 'limit' => isset($parameters['limit']) ? $parameters['limit'] : 10,
+ ]);
+ }
+ public static function getName()
+ {
+ return 'LatestContent';
+ }
+ /**
+ * Returns an array listing the parameters supported by the QueryType.
+ * @return array
+ */
+ public function getSupportedParameters()
+ {
+ return ['type', 'limit'];
+ }
+}
+```
+
+In content view configuration, use the name of the Query Types as defined in `getName`.
+
+``` yaml
+content_view:
+ full:
+ latest:
+ controller: ez_query:locationQueryAction
+ template: content/view/full/latest.html.twig
+ match:
+ Identifier\ContentType: "latest"
+ params:
+ query:
+ query_type: LatestContent
+ parameters:
+ parentLocationId: '@=location.id'
+ assign_results_to: latest
+```
+
+Your Query Type must be [registered as a service](#registering-the-querytype-into-the-service-container).
+
### Configuration details
#### `controller`
@@ -285,11 +439,11 @@ The Query is configured in a `query` hash in `params`, you could specify the Que
- This is the name of the Twig variable that will be assigned the results.
- Note that the results are the SearchResult object returned by the SearchService.
-#### QueryType objects
+### Query Type objects
-QueryType is an object that builds a Query. It is different from [Public API queries](../api/public_php_api.md).
+Query Type is an object that builds a Query. It is different from [Public API queries](../api/public_php_api.md).
-To make a new QueryType available to the Query Controller, you need to create a PHP class that implements the QueryType interface, then register it as such in the Service Container.
+To make a new Query Type available to the Query Controller, you need to create a PHP class that implements the QueryType interface, then register it as such in the Service Container.
For more information about the [Service Container on its documentation page](service_container.md).
@@ -338,49 +492,6 @@ A QueryType may accept parameters, including string, array and other types, depe
The implementations should use Symfony's `OptionsResolver` for parameter handling and resolution.
-### QueryType example: latest content
-
-This QueryType returns a Query that searches for **the 10 last published Content items, ordered by reverse publishing date**.
-It accepts an optional `type` parameter that can be set to a Content Type identifier:
-
-``` php
- new Query\Criterion\LogicalAnd($criteria),
- 'sortClauses' => [new Query\SortClause\DatePublished()],
- 'limit' => isset($parameters['limit']) ? $parameters['limit'] : 10,
- ]);
- }
- public static function getName()
- {
- return 'LatestContent';
- }
- /**
- * Returns an array listing the parameters supported by the QueryType.
- * @return array
- */
- public function getSupportedParameters()
- {
- return ['type', 'limit'];
- }
-}
-```
-
### Naming of QueryTypes
Each QueryType is named after what is returned by `getName()`. **Names must be unique.** A warning will be thrown during compilation if there is a conflict, and the resulting behavior will be unpredictable.
diff --git a/docs/guide/displaying_children_of_a_content_item.md b/docs/guide/displaying_children_of_a_content_item.md
index e0b30c0acb..caac3ddc1d 100644
--- a/docs/guide/displaying_children_of_a_content_item.md
+++ b/docs/guide/displaying_children_of_a_content_item.md
@@ -16,46 +16,16 @@ This procedure demonstrates how to use these three methods to display all childr
The Query Controller is a pre-defined custom content view Controller that runs a Repository Query
that you can use together with the Content query Field Type.
-The Query Type in this example is contained an `src/QueryType/LocationChildrenQueryType.php` file
-which generates a Query that retrieves the children of the current Location.
-
-``` php
- new ParentLocationId($parameters['parentLocationId']),
- ]);
- }
-
- public function getSupportedParameters()
- {
- return ['parentLocationId'];
- }
-
- public static function getName()
- {
- return 'LocationChildren';
- }
-}
-```
+This example uses the built-in `Children` Query Type
+which retrieves the children of the current Location.
To use the Query Type with a Content query Field, add the Field to your Folder Content Type's definition.
-Select "Location children" as the Query type. Provide the `parentLocationId` parameter
+Select "Children" as the Query Type. Provide the `content` parameter
that the Query type requires:
```
-parentLocationId: '@=mainLocation.id'
+content: '@=content'
```
You can paginate the query results by checking the **Enable pagination** box and selecting a limit of results per page.
@@ -89,25 +59,25 @@ The query results are available in the `items` variable:
## Using the Query Controller
-You can also use the same Query Type as above together with the Query Controller.
+You can also use the `Children` Query Type together with the Query Controller.
In your [standard view configuration](../guide/content_rendering.md#configuring-views-the-viewprovider) file, under `content_view`, add a section that indicates when this Controller will be used. It is similar to regular view config, but contains additional information:
``` yaml
folder:
- controller: ez_query:locationQueryAction
+ controller: ez_query:contentQueryAction
template: full/folder.html.twig
match:
Identifier\ContentType: folder
params:
query:
- query_type: LocationChildren
+ query_type: Children
parameters:
- parentLocationId: '@=location.id'
+ location: '@=location'
assign_results_to: items
```
-In this case the `controller` key points to the Query Controller's `locationQuery` action. `assign_results_to` identifies the parameter containing all the retrieved children that will later be used in the templates, like here in `templates/full/folder.html.twig`:
+In this case the `controller` key points to the Query Controller's `contentQuery` action. `assign_results_to` identifies the parameter containing all the retrieved children that will later be used in the templates, like here in `templates/full/folder.html.twig`:
``` html+twig
{{ ez_content_name(content) }}
diff --git a/docs/guide/templates.md b/docs/guide/templates.md
index 172ce59e5b..d4fe04a8ba 100644
--- a/docs/guide/templates.md
+++ b/docs/guide/templates.md
@@ -446,6 +446,42 @@ For example:
For details on listing children of a Content item, for example all content contained in a folder, see [Displaying children of a Content item](displaying_children_of_a_content_item.md).
+### Non-content related Query Types
+
+If you use [Query Types](controllers.md#query-controller) that do not make use of the current content or Location
+(e.g. rendering a list of latest blog posts, or a menu),
+you can render them in your templates using `ez_render__query` (e.g. `ez_render_content_query`) Twig functions
+or their ESI equivalents: `ez_render_content_query_esi`.
+
+``` html+twig
+{{ ez_render_content_query({
+ 'query': {
+ 'query_type': 'LatestContent',
+ 'assign_results_to': 'latest_articles'
+ },
+ 'template': 'latest/latest.html.twig',
+}) }}
+```
+
+You can also set pagination using the Twig function:
+
+``` html+twig
+{{ ez_render_location_query({
+ 'query': {
+ 'query_type': 'LatestContent',
+ 'assign_results_to': 'latest_articles'
+ },
+ 'pagination': {
+ 'enabled': true,
+ 'limit': 5,
+ 'page_param': 'page'
+ },
+ 'template': 'latest/latest.html.twig',
+}) }}
+```
+
+Using this function does not require adding anything to your content view configuration.
+
#### Rendering and cache
##### ESI