Improved examples

doc/examples/README.md

@@ -0,0 +1,24 @@
+The examples in this directory are meant to present different usages for the query field.
+They all come with their own query type, as well as a README file that guides you into using the example.
+
+## List of examples
+
+### `children`
+[documentation](children/README.md)
+
+Children of a content item: images of a gallery, most recent articles of a category...
+
+### `map_location_distance`
+[documentation](map_location_distance/README.md)
+
+Items located within a given distance of an item's geographical location.
+
+### `reverse_relations`
+[documentation](reverse_relations/README.md)
+
+Items related to the current item.
+
+### `ancestors`
+[documentation](children/README.md)
+
+Ancestors of a type.

doc/examples/ancestors/AncestorsOfContentQueryType.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * @copyright Copyright (C) eZ Systems AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+namespace App\QueryType;
+
+use eZ\Publish\API\Repository\LocationService;
+use eZ\Publish\API\Repository\Values\Content\Content;
+use eZ\Publish\API\Repository\Values\Content\Location;
+use eZ\Publish\API\Repository\Values\Content\Query;
+use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
+use eZ\Publish\Core\Base\Exceptions\InvalidArgumentException;
+use eZ\Publish\Core\QueryType\QueryType;
+
+class AncestorsOfContentQueryType implements QueryType
+{
+    /**
+     * @var \eZ\Publish\API\Repository\LocationService
+     */
+    private $locationService;
+
+    public function __construct(LocationService $locationService)
+    {
+        $this->locationService = $locationService;
+    }
+
+    public function getQuery(array $parameters = [])
+    {
+        if ($parameters['content'] instanceof Content) {
+            $pathStrings = array_map(
+                function (Location $location) {
+                    return $location->pathString;
+                },
+                $this->locationService->loadLocations($parameters['content']->contentInfo)
+            );
+        } else {
+            throw new InvalidArgumentException('content', 'should be of type API\Content');
+        }
+
+        $filter = new Criterion\LogicalAnd([
+            new Criterion\Ancestor($pathStrings),
+            new Criterion\ContentTypeIdentifier($parameters['type']),
+        ]);
+
+        return new Query([
+            'filter' => $filter,
+        ]);
+    }
+
+    public function getSupportedParameters()
+    {
+        return ['content', 'type'];
+    }
+
+    public static function getName()
+    {
+        return 'AncestorsOfContent';
+    }
+}

doc/examples/ancestors/README.md

@@ -0,0 +1,18 @@
+# Query field: ancestors example
+A field that, given a content item, returns the ancestors of that item's locations that are of a given type. Example use-case: 
+
+## Example
+Images are added as children of Gallery items.
+The `images.gallery` field returns the galleries any image is part of.
+
+### Query Type
+`AncestorsOfContent`
+
+### Returned type
+Image
+
+### Parameters
+```yaml
+content: "@=content"
+type: "@=returnedType"
+```

doc/examples/children/ChildrenQueryType.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace AppBundle\QueryType;
+
+use eZ\Publish\Core\QueryType\QueryType;
+use eZ\Publish\API\Repository\Values\Content\Query;
+
+class ChildrenQueryType implements QueryType
+{
+    public function getQuery(array $parameters = [])
+    {
+        $options = [];
+
+        $criteria = [
+            new Query\Criterion\Visibility(Query\Criterion\Visibility::VISIBLE),
+        ];
+
+        if (!empty($parameters['parent_location_id'])) {
+            $criteria[] = new Query\Criterion\ParentLocationId($parameters['parent_location_id']);
+        } else {
+            $criteria[] = new Query\Criterion\MatchNone();
+        }
+
+        if (!empty($parameters['included_content_type_identifier'])) {
+            $criteria[] = new Query\Criterion\ContentTypeIdentifier($parameters['included_content_type_identifier']);
+        }
+
+        $options['filter'] = new Query\Criterion\LogicalAnd($criteria);
+
+        if (isset($parameters['limit'])) {
+            $options['limit'] = $parameters['limit'];
+        }
+
+        $options['sortClauses'] = [new Query\SortClause\DatePublished(Query::SORT_DESC)];
+
+        return new Query($options);
+    }
+
+    public static function getName()
+    {
+        return 'AppBundle:Children';
+    }
+
+    public function getSupportedParameters()
+    {
+        return [
+            'parent_location_id',
+            'included_content_type_identifier',
+            'limit',
+            'whatever'
+        ];
+    }
+}

doc/examples/children/README.md

@@ -0,0 +1,19 @@
+### Gallery images query field
+A field that lists the children of a given type below the current location.
+
+#### Content type configuration
+The following assumes a "gallery" content type with an "images" query field.
+The images are the sub-items of the gallery.
+
+
+##### Query type
+`AppBundle:Children` (defined in `ChildrenQueryType.php`)
+
+##### Returned type
+Image
+
+##### Parameters
+```yaml
+parent_location_id: '@=mainLocation.id'
+included_content_type_identifier: '@=returnedType'
+```

doc/examples/children/templates/content/view/content_query_field/gallery_images.html.twig

@@ -0,0 +1,12 @@
+<div class="row text-center text-lg-left">
+{% for item in items %}
+    {{ render(controller("ez_content:viewAction", {
+        "contentId": item.id,
+        "viewType": itemViewType
+    })) }}
+{% endfor %}
+</div>
+
+{% if isPaginationEnabled %}
+    {{ pagerfanta( items, 'ez', {'routeName': location, 'pageParameter': pageParameter } ) }}
+{% endif %}

doc/examples/children/templates/content/view/line/images.html.twig

@@ -0,0 +1,11 @@
+<div class="col-lg-3 col-md-4 col-6">
+    {{ ez_render_field(
+        content, 'image',
+        {
+            parameters: {
+                alias: 'small',
+                attrs: {class: 'img-fluid img-thumbnail'}
+            }
+        }
+    ) }}
+</div>

doc/examples/children/views.yml

@@ -0,0 +1,17 @@
+ezpublish:
+    systems:
+        site:
+            content_view:
+                # Customize the layout around all the images
+                content_query_field:
+                    gallery_images:
+                        match:
+                            Identifier\ContentType: gallery
+                            Identifier\FieldDefinition: images
+                        template: "content/view/content_query_field/gallery_images.html.twig"
+                # Customize the layout of each image
+                line:
+                    images:
+                        match:
+                            Identifier\ContentType: image
+                        template: "content/view/line/images.html.twig"

doc/examples/nearby_places/README.md → doc/examples/map_location_distance/README.md

@@ -1,13 +1,12 @@
 ### Nearby places query field
-
-A field that lists Place items located close to the current item.
+A field that returns items based on their distance relative to the current item.
 
 #### Content type configuration
 The following assumes a "place" content item with a "location" map location
 field definition.
 
 ##### Query type
-"Nearby places" (see [NearbyPlacesQueryType](NearbyPlacesQueryType.php).
+"RelativeDistance" (see [NearbyPlacesQueryType](NearbyPlacesQueryType.php).
 
 ##### Parameters
 ```yaml

doc/examples/nearby_places/NearbyPlacesQueryType.php → doc/examples/map_location_distance/RelativeDistanceQueryType.php

@@ -4,13 +4,13 @@
  * @copyright Copyright (C) eZ Systems AS. All rights reserved.
  * @license For full copyright and license information view LICENSE file distributed with this source code.
  */
-namespace App\QueryType;
+namespace AppBundle\QueryType;
 
 use eZ\Publish\API\Repository\Values\Content\Query;
 use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
 use eZ\Publish\Core\QueryType\QueryType;
 
-class NearbyPlacesQueryType implements QueryType
+class RelativeDistanceQueryType implements QueryType
 {
     public function getQuery(array $parameters = [])
     {
@@ -35,6 +35,6 @@ public function getSupportedParameters()
 
     public static function getName()
     {
-        return 'NearbyPlaces';
+        return 'RelativeDistance';
     }
 }

doc/examples/reverse_relations/README.md

@@ -0,0 +1,43 @@
+### Partners references query field
+A field that lists the references developed by a partner.
+
+#### Content type configuration
+The "reference' content type with has a "partners" relation list field. Each partner involved in the reference is added.
+
+The "partner" content type has a "references" content query field. It lists all references that include that partner.
+
+##### Query type
+AppBundle:RelatedToContent
+
+##### Returned type
+Reference
+
+##### Parameters
+```yaml
+from_field: partners
+sort_by: Name
+content_type: '@=returnedType'
+to_content: '@=content'
+```
+
+#### Layout customization
+```yaml
+ezpublish:
+    systems:
+        site:
+            languages: [eng-GB]
+            content_view:
+                # Customize the layout around all the images
+                content_query_field:
+                    partner_references:
+                        match:
+                            Identifier\ContentType: partner
+                            Identifier\FieldDefinition: references
+                        template: "content/view/content_query_field/partner_references.html.twig"
+                # Customize the layout of each image
+                line:
+                    reference:
+                        match:
+                            Identifier\ContentType: reference
+                        template: "content/view/line/reference.html.twig"
+```

doc/examples/reverse_relations/RelatedToContentQueryType.php

@@ -0,0 +1,74 @@
+<?php
+/**
+ * @copyright Copyright (C) eZ Systems AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+
+namespace AppBundle\QueryType;
+
+use eZ\Publish\API\Repository\Values\Content\Content;
+use eZ\Publish\API\Repository\Values\Content\Query;
+use eZ\Publish\Core\QueryType\OptionsResolverBasedQueryType;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+/**
+ * For a given content, return items that have a relation to it using a specific field identifier.
+ *
+ * Parameters:
+ * - Content to_content: the content item that is the target of the relations
+ * - string from_field: the identifier of the field that has the relation
+ * - string|string[] content_type (optional): a content type or set of content type to filter on
+ *   Default: name
+ *
+ * @todo add sort direction support
+ */
+class RelatedToContentQueryType extends OptionsResolverBasedQueryType
+{
+    /**
+     * @inheritDoc
+     */
+    protected function configureOptions(OptionsResolver $optionsResolver)
+    {
+        $optionsResolver->setDefined(['to_content', 'from_field', 'content_type', 'sort_by']);
+        $optionsResolver->setRequired(['to_content', 'from_field']);
+        $optionsResolver->addAllowedTypes('to_content', Content::class);
+        $optionsResolver->addAllowedTypes('from_field', 'string');
+        $optionsResolver->addAllowedTypes('content_type', 'string');
+
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected function doGetQuery(array $parameters)
+    {
+        $query = new Query();
+        $query->filter = new Query\Criterion\LogicalAnd([
+            new Query\Criterion\FieldRelation($parameters['from_field'], Query\Criterion\Operator::CONTAINS, [$parameters['to_content']->id])
+        ]);
+        if (isset($parameters['content_type'])) {
+            $query->filter->criteria[] = new Query\Criterion\ContentTypeIdentifier($parameters['content_type']);
+        }
+
+        if (isset($parameters['sort_by'])) {
+            $sortClauseClass = 'Query\SortClause' . $parameters['sort_by'];
+            if (class_exists($sortClauseClass)) {
+                $query->sortClauses[] = new $sortClauseClass(Query::SORT_ASC);
+            }
+        }
+
+        if (empty($query->sortClauses)) {
+            $query->sortClauses[] = new Query\SortClause\ContentName(Query::SORT_ASC);
+        }
+
+        return $query;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public static function getName()
+    {
+        return 'RelatedToContent';
+    }
+}