Merge pull request #100 from johannessteu/feature/geo-distance-sort

[TASK] Add a generic sort operation

This changes adds a generic sort operation that can be used to create any kind of sorting that ElasticSearch supports.

Author: daniellienert

Classes/Flowpack/ElasticSearch/ContentRepositoryAdaptor/Eel/ElasticSearchQueryBuilder.php

@@ -171,19 +171,15 @@ public function nodeType($nodeType)
      */
     public function sortDesc($propertyName)
     {
-        if (!isset($this->request['sort'])) {
-            $this->request['sort'] = array();
-        }
+        $configuration = [
+            $propertyName => ['order' => 'desc']
+        ];
 
-        // http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html
-        $this->request['sort'][] = array(
-            $propertyName => array('order' => 'desc')
-        );
+        $this->sort($configuration);
 
         return $this;
     }
 
-
     /**
      * Sort ascending by $propertyName
      *
@@ -192,20 +188,34 @@ public function sortDesc($propertyName)
      * @api
      */
     public function sortAsc($propertyName)
+    {
+        $configuration = [
+            $propertyName => ['order' => 'asc']
+        ];
+
+        $this->sort($configuration);
+
+        return $this;
+    }
+
+    /**
+     * Add a $configuration sort filter to the request
+     *
+     * @param array $configuration
+     * @return ElasticSearchQueryBuilder
+     * @api
+     */
+    public function sort($configuration)
     {
         if (!isset($this->request['sort'])) {
             $this->request['sort'] = array();
         }
 
-        // http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-sort.html
-        $this->request['sort'][] = array(
-            $propertyName => array('order' => 'asc')
-        );
+        $this->request['sort'][] = $configuration;
 
         return $this;
     }
 
-
     /**
      * output only $limit records
      *

Classes/Flowpack/ElasticSearch/ContentRepositoryAdaptor/Eel/ElasticSearchQueryResult.php

@@ -192,7 +192,7 @@ public function getAccessibleCount()
     public function getAggregations()
     {
         $this->initialize();
-        if (array_key_exists("aggregations", $this->result)) {
+        if (array_key_exists('aggregations', $this->result)) {
             return $this->result['aggregations'];
         }
         return array();
@@ -229,6 +229,23 @@ public function searchHitForNode(NodeInterface $node)
         return $this->elasticSearchQuery->getQueryBuilder()->getFullElasticSearchHitForNode($node);
     }
 
+    /**
+     * Returns the array with all sort values for a given node. The values are fetched from the raw content
+     * ElasticSearch returns within the hit data
+     *
+     * @param NodeInterface $node
+     * @return array
+     */
+    public function getSortValuesForNode(NodeInterface $node)
+    {
+        $hit = $this->searchHitForNode($node);
+        if (is_array($hit) && array_key_exists('sort', $hit)) {
+            return $hit['sort'];
+        }
+
+        return array();
+    }
+
     /**
      * @param string $methodName
      * @return boolean

Classes/Flowpack/ElasticSearch/ContentRepositoryAdaptor/ViewHelpers/GetHitArrayForNodeViewHelper.php

@@ -0,0 +1,58 @@
+<?php
+namespace Flowpack\ElasticSearch\ContentRepositoryAdaptor\ViewHelpers;
+
+/*                                                                                                  *
+ * This script belongs to the TYPO3 Flow package "Flowpack.ElasticSearch.ContentRepositoryAdaptor". *
+ *                                                                                                  *
+ * It is free software; you can redistribute it and/or modify it under                              *
+ * the terms of the GNU Lesser General Public License, either version 3                             *
+ *  of the License, or (at your option) any later version.                                          *
+ *                                                                                                  *
+ * The TYPO3 project - inspiring people to share!                                                   *
+ *                                                                                                  */
+
+use Flowpack\ElasticSearch\ContentRepositoryAdaptor\Eel\ElasticSearchQueryResult;
+use TYPO3\TYPO3CR\Domain\Model\NodeInterface;
+use TYPO3\Flow\Annotations as Flow;
+use TYPO3\Fluid\Core\ViewHelper\AbstractViewHelper;
+
+/**
+ * View helper to get the raw "hits" array of an ElasticSearchQueryResult for a
+ * specific node.
+ *
+ * = Examples =
+ *
+ * <code title="Basic usage">
+ * {esCrAdapter:geHitArrayForNode(queryResultObject: result, node: node)}
+ * </code>
+ * <output>
+ * array
+ * </output>
+ *
+ * You can also return specific data
+ * <code title="Fetch specific data">
+ * {esCrAdapter:geHitArrayForNode(queryResultObject: result, node: node, path: 'sort')}
+ * </code>
+ * <output>
+ * array or single value
+ * </output>
+ */
+class GetHitArrayForNodeViewHelper extends AbstractViewHelper
+{
+    /**
+     * @param ElasticSearchQueryResult $queryResultObject
+     * @param NodeInterface $node
+     * @param array|string $path
+     * @return array
+     */
+    public function render(ElasticSearchQueryResult $queryResultObject, NodeInterface $node, $path = NULL)
+    {
+        $hitArray = $queryResultObject->searchHitForNode($node);
+
+        if (!empty($path)) {
+            return \TYPO3\Flow\Utility\Arrays::getValueByPath($hitArray, $path);
+        }
+
+        return $hitArray;
+    }
+}

README.md

@@ -264,7 +264,7 @@ your node data. Aggregations also allows you to build a complex filter for e.g.
 
 **Aggregation methods**
 Right now there are two methods implemented. One generic `aggregation` function that allows you to add any kind of
-aggregation definition and a pre-configured `fieldBasedAggregation`. Both methods can be added to your TS search query. 
+aggregation definition and a pre-configured `fieldBasedAggregation`. Both methods can be added to your TS search query.
 You can nest aggregations by providing a parent name.
 
 * `aggregation($name, array $aggregationDefinition, $parentPath = NULL)` -- generic method to add a $aggregationDefinition under a path $parentPath with the name $name
@@ -278,7 +278,7 @@ a property price:
 ```
 nodes = ${Search.query(site)...fieldBasedAggregation("avgprice", "price", "avg").execute()}
 ```
-Now you can access your aggregations inside your fluid template with 
+Now you can access your aggregations inside your fluid template with
 ```
 {nodes.aggregations}
 ```
@@ -290,7 +290,7 @@ to know the average price for all your colors you just nest an aggregation in yo
 nodes = ${Search.query(site)...fieldBasedAggregation("colors", "color").fieldBasedAggregation("avgprice", "price", "avg", "colors").execute()}
 ```
 The first `fieldBasedAggregation` will add a simple terms aggregation (https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html)
-with the name colors. So all different colors of your nodetype will be listed here. 
+with the name colors. So all different colors of your nodetype will be listed here.
 The second `fieldBasedAggregation` will add another sub-aggregation named avgprice below your colors-aggregation.
 
 You can nest even more aggregations like this:
@@ -323,7 +323,7 @@ prototype(Vendor.Name:FilteredProductList) {
 	searchFilter = TYPO3.TypoScript:RawArray {
 		sku = ${String.split(q(node).property("products"), ",")}
 	}
-	
+
 	# Search for all products that matches your queryFilter and add aggregations
 	filter = ${Search.query(site).nodeType("Vendor.Name:Product").queryFilterMultiple(this.searchFilter, "must").fieldBasedAggregation("color", "color").fieldBasedAggregation("size", "size").execute()}
 
@@ -347,7 +347,7 @@ prototype(Vendor.Name:FilteredProductList) {
 ```
 
 In the first lines we will add a new searchFilter variable and add your selected sku's as a filter. Based on this selection
-we will add two aggregations of type terms. You can access the filter in your template with `{filter.aggregation}`. With 
+we will add two aggregations of type terms. You can access the filter in your template with `{filter.aggregation}`. With
 this information it is easy to create a form with some select fields with all available options. If you submit the form
 just call the same page and add the get parameter color and/or size.
 The next lines will parse those parameters and add them to the searchFilter. Based on your selection all products will
@@ -371,6 +371,95 @@ your filterable properties like this:
           index: 'not_analyzed'
 ```
 
+## Sorting
+
+This package adapts ElasticSearchs sorting capabilities. You can add multiple sort operations to your query.
+Right now there are three methods you can use:
+
+* `sortAsc('propertyName')`
+* `sortDesc('propertyName')`
+* `sort('configuration')`
+
+Just append those method to your query like this:
+```
+# sort ascending by property title
+nodes = ${q(Search.query(site).....sortAsc("title").execute())}
+
+# sort for multiple properties
+nodes = ${q(Search.query(site).....sortAsc("title").sortDesc("name").execute())}
+
+# custom sort opertation
+geoSorting = TYPO3.TypoScript:RawArray {
+    _geo_distance = TYPO3.TypoScript:RawArray {
+        latlng = TYPO3.TypoScript:RawArray {
+            lat = 51.512711
+            lon = 7.453084
+        }
+        order = "plane"
+        unit = "km"
+        distance_type = "sloppy_arc"
+    }
+}
+nodes = ${Search.query(site).....sort(this.geoSorting).execute()}
+
+```
+Check https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html for more configuration
+options.
+
+### Example with pagination and sort by distance
+This is how a more complex example could look like. Imagine you a want to render a list of nodes and in addition to each
+node you want to display the distance to a specific point.
+
+First of all you have to define a property in your NodeTypes.yaml for your node where to store lat/lon information's:
+```
+'Vendor.Name:Retailer':
+  properties:
+    'latlng':
+      type: string
+      search:
+        elasticSearchMapping:
+          type: "geo_point"
+```
+
+Query your nodes in your TypoScript:
+```
+geoSorting = TYPO3.TypoScript:RawArray {
+    _geo_distance = TYPO3.TypoScript:RawArray {
+        latlng = TYPO3.TypoScript:RawArray {
+            lat = 51.512711
+            lon = 7.453084
+        }
+        order = "plane"
+        unit = "km"
+        distance_type = "sloppy_arc"
+    }
+}
+nodes = ${Search.query(site).nodeType('Vendor.Name:Retailer').sort(this.geoSorting)}
+```
+
+Now you can paginate that nodes in your template. To get your actually distance for each node use
+the `GetHitArrayForNodeViewHelper`:
+```
+{namespace es=Flowpack\ElasticSearch\ContentRepositoryAdaptor\ViewHelpers}
+
+<typo3cr:widget.paginate query="{nodes}" as="paginatedNodes">
+    <f:for each="{paginatedNodes}" as="singleNode">
+        {singleNode.name} - <es:getHitArrayForNode queryResultObject="{nodes}" node="{singleNode}" path="sort.0" />
+    </f:for>
+</typo3cr:widget.paginate>
+
+```
+
+The ViewHelper will use \TYPO3\Flow\Utility\Arrays::getValueByPath() to return a specified path. So you can make use
+of an array or a string. Check the documentation \TYPO3\Flow\Utility\Arrays::getValueByPath() for more informations.
+
+**Important notice**
+The ViewHelper GetHitArrayForNode will return the raw hit result array. The path poperty allows you to access some
+specific data like the the sort data. If there is only one value for your path the value will be returned.
+If there is more data the full array will be returned by GetHitArrayForNode-VH. So you might have to use the
+ForViewHelper to access your sort values.
+
+
 ## Fulltext Search / Indexing
 
 When searching in a fulltext index, we want to show Pages, or, generally speaking, everything

Tests/Functional/Eel/ElasticSearchQueryTest.php

@@ -67,7 +67,7 @@ public function setUp()
     {
         parent::setUp();
         $this->workspaceRepository = $this->objectManager->get('TYPO3\TYPO3CR\Domain\Repository\WorkspaceRepository');
-        $liveWorkspace = new Workspace("live");
+        $liveWorkspace = new Workspace('live');
         $this->workspaceRepository->add($liveWorkspace);
 
         $this->nodeTypeManager = $this->objectManager->get('TYPO3\TYPO3CR\Domain\Service\NodeTypeManager');
@@ -128,8 +128,8 @@ public function filterLimitQuery()
      */
     public function fieldBasedAggregations()
     {
-        $aggregationTitle = "titleagg";
-        $result = $this->queryBuilder->query($this->context->getRootNode())->fieldBasedAggregation($aggregationTitle, "title")->execute()->getAggregations();
+        $aggregationTitle = 'titleagg';
+        $result = $this->queryBuilder->query($this->context->getRootNode())->fieldBasedAggregation($aggregationTitle, 'title')->execute()->getAggregations();
 
         $this->assertArrayHasKey($aggregationTitle, $result);
 
@@ -170,19 +170,31 @@ public function termSuggestion()
      */
     public function nodesWillBeSortedDesc()
     {
-        $descendingResult = $this->queryBuilder->query($this->context->getRootNode())->sortDesc("title")->execute();
+        $descendingResult = $this->queryBuilder->query($this->context->getRootNode())->sortDesc('title')->execute();
         $node = $descendingResult->getFirst();
-        $this->assertEquals("egg", $node->getProperty("title"), "Asserting a desc sort order by property title");
+        $this->assertEquals('egg', $node->getProperty('title'), 'Asserting a desc sort order by property title');
     }
 
     /**
      * @test
      */
     public function nodesWillBeSortedAsc()
     {
-        $ascendingResult = $this->queryBuilder->query($this->context->getRootNode())->sortAsc("title")->execute();
+        $ascendingResult = $this->queryBuilder->query($this->context->getRootNode())->sortAsc('title')->execute();
         $node = $ascendingResult->getFirst();
-        $this->assertEquals("chicken", $node->getProperty("title"), "Asserting a asc sort order by property title");
+        $this->assertEquals('chicken', $node->getProperty('title'), 'Asserting a asc sort order by property title');
+    }
+
+    /**
+     * @test
+     */
+    public function sortValuesAreReturned()
+    {
+        $result = $this->queryBuilder->query($this->context->getRootNode())->sortAsc('title')->execute();
+
+        foreach ($result as $node) {
+            $this->assertEquals(array($node->getProperty('title')), $result->getSortValuesForNode($node));
+        }
     }
 
     /**
@@ -205,7 +217,6 @@ protected function createNodesForNodeSearchTest()
         $translatedNode3 = $dimensionContext->adoptNode($newNode3, TRUE);
         $translatedNode3->setProperty('title', 'Ei');
 
-
         $this->persistenceManager->persistAll();
         $this->nodeIndexCommandController->buildCommand();
     }