From ee891c8895181a288d7445eafaf9e73be9a74beb Mon Sep 17 00:00:00 2001 From: Bertrand Dunogier Date: Fri, 20 Dec 2019 17:44:09 +0100 Subject: [PATCH] Completed examples Unified documentation, added new ones, made them more generic. --- doc/examples/README.md | 20 +++++ .../ancestors/AncestorsOfContentQueryType.php | 61 +++++++++++++++ doc/examples/ancestors/README.md | 18 +++++ doc/examples/children/ChildrenQueryType.php | 53 +++++++++++++ doc/examples/children/README.md | 19 +++++ .../gallery_images.html.twig | 12 +++ .../content/view/line/images.html.twig | 11 +++ doc/examples/children/views.yml | 17 +++++ .../README.md | 5 +- .../RelativeDistanceQueryType.php} | 6 +- doc/examples/reverse_relations/README.md | 43 +++++++++++ .../RelatedToContentQueryType.php | 74 +++++++++++++++++++ 12 files changed, 333 insertions(+), 6 deletions(-) create mode 100644 doc/examples/README.md create mode 100644 doc/examples/ancestors/AncestorsOfContentQueryType.php create mode 100644 doc/examples/ancestors/README.md create mode 100644 doc/examples/children/ChildrenQueryType.php create mode 100644 doc/examples/children/README.md create mode 100644 doc/examples/children/templates/content/view/content_query_field/gallery_images.html.twig create mode 100644 doc/examples/children/templates/content/view/line/images.html.twig create mode 100644 doc/examples/children/views.yml rename doc/examples/{nearby_places => map_location_distance}/README.md (68%) rename doc/examples/{nearby_places/NearbyPlacesQueryType.php => map_location_distance/RelativeDistanceQueryType.php} (89%) create mode 100644 doc/examples/reverse_relations/README.md create mode 100644 doc/examples/reverse_relations/RelatedToContentQueryType.php diff --git a/doc/examples/README.md b/doc/examples/README.md new file mode 100644 index 0000000..1570f1f --- /dev/null +++ b/doc/examples/README.md @@ -0,0 +1,20 @@ +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. diff --git a/doc/examples/ancestors/AncestorsOfContentQueryType.php b/doc/examples/ancestors/AncestorsOfContentQueryType.php new file mode 100644 index 0000000..44c64c8 --- /dev/null +++ b/doc/examples/ancestors/AncestorsOfContentQueryType.php @@ -0,0 +1,61 @@ +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'; + } +} diff --git a/doc/examples/ancestors/README.md b/doc/examples/ancestors/README.md new file mode 100644 index 0000000..db7b8f6 --- /dev/null +++ b/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" +``` diff --git a/doc/examples/children/ChildrenQueryType.php b/doc/examples/children/ChildrenQueryType.php new file mode 100644 index 0000000..ee11f2f --- /dev/null +++ b/doc/examples/children/ChildrenQueryType.php @@ -0,0 +1,53 @@ + +{% for item in items %} + {{ render(controller("ez_content:viewAction", { + "contentId": item.id, + "viewType": itemViewType + })) }} +{% endfor %} + + +{% if isPaginationEnabled %} + {{ pagerfanta( items, 'ez', {'routeName': location, 'pageParameter': pageParameter } ) }} +{% endif %} diff --git a/doc/examples/children/templates/content/view/line/images.html.twig b/doc/examples/children/templates/content/view/line/images.html.twig new file mode 100644 index 0000000..47944ca --- /dev/null +++ b/doc/examples/children/templates/content/view/line/images.html.twig @@ -0,0 +1,11 @@ +
+ {{ ez_render_field( + content, 'image', + { + parameters: { + alias: 'small', + attrs: {class: 'img-fluid img-thumbnail'} + } + } + ) }} +
diff --git a/doc/examples/children/views.yml b/doc/examples/children/views.yml new file mode 100644 index 0000000..574c309 --- /dev/null +++ b/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" diff --git a/doc/examples/nearby_places/README.md b/doc/examples/map_location_distance/README.md similarity index 68% rename from doc/examples/nearby_places/README.md rename to doc/examples/map_location_distance/README.md index db161dc..390a42c 100644 --- a/doc/examples/nearby_places/README.md +++ b/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 diff --git a/doc/examples/nearby_places/NearbyPlacesQueryType.php b/doc/examples/map_location_distance/RelativeDistanceQueryType.php similarity index 89% rename from doc/examples/nearby_places/NearbyPlacesQueryType.php rename to doc/examples/map_location_distance/RelativeDistanceQueryType.php index 9a1ccc6..dca8998 100644 --- a/doc/examples/nearby_places/NearbyPlacesQueryType.php +++ b/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'; } } diff --git a/doc/examples/reverse_relations/README.md b/doc/examples/reverse_relations/README.md new file mode 100644 index 0000000..389dcdc --- /dev/null +++ b/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" +``` diff --git a/doc/examples/reverse_relations/RelatedToContentQueryType.php b/doc/examples/reverse_relations/RelatedToContentQueryType.php new file mode 100644 index 0000000..4c9e4c9 --- /dev/null +++ b/doc/examples/reverse_relations/RelatedToContentQueryType.php @@ -0,0 +1,74 @@ +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'; + } +}