IBX-6878: Customize search sorting (#2226)

---------

Co-authored-by: Adrien Dupuis <[email protected]>
Co-authored-by: Adam Wójs <[email protected]>
Co-authored-by: julitafalcondusza <[email protected]>
Co-authored-by: Tomasz Dąbrowski <[email protected]>
Co-authored-by: Marek Nocoń <[email protected]>
(cherry picked from commit 9d37154)

Author: 5 people

code_samples/back_office/search/config/append_to_services.yaml

@@ -26,3 +26,7 @@ services:
             $groupIdentifier: 'global-search-autocomplete-product'
         tags:
             - { name: ibexa.admin_ui.component, group: global-search-autocomplete-templates }
+
+    App\Search\SortingDefinition\Provider\SectionNameSortingDefinitionProvider:
+        tags:
+            - name: ibexa.search.sorting_definition.provider

code_samples/back_office/search/src/Search/SortingDefinition/Provider/SectionNameSortingDefinitionProvider.php

@@ -0,0 +1,51 @@
+<?php declare(strict_types=1);
+
+namespace App\Search\SortingDefinition\Provider;
+
+use Ibexa\Contracts\Core\Repository\Values\Content\Query;
+use Ibexa\Contracts\Core\Repository\Values\Content\Query\SortClause;
+use Ibexa\Contracts\Search\SortingDefinition\SortingDefinition;
+use Ibexa\Contracts\Search\SortingDefinition\SortingDefinitionProviderInterface;
+use JMS\TranslationBundle\Model\Message;
+use JMS\TranslationBundle\Translation\TranslationContainerInterface;
+use Symfony\Contracts\Translation\TranslatorInterface;
+
+final class SectionNameSortingDefinitionProvider implements SortingDefinitionProviderInterface, TranslationContainerInterface
+{
+    private TranslatorInterface $translator;
+
+    public function __construct(TranslatorInterface $translator)
+    {
+        $this->translator = $translator;
+    }
+
+    public function getSortingDefinitions(): array
+    {
+        return [
+            new SortingDefinition(
+                'section_asc',
+                $this->translator->trans('sort_definition.section_name_asc.label'),
+                [
+                    new SortClause\SectionName(Query::SORT_ASC),
+                ],
+                333
+            ),
+            new SortingDefinition(
+                'section_desc',
+                $this->translator->trans('sort_definition.section_name_desc.label'),
+                [
+                    new SortClause\SectionName(Query::SORT_DESC),
+                ],
+                369
+            ),
+        ];
+    }
+
+    public static function getTranslationMessages(): array
+    {
+        return [
+            (new Message('sort_definition.section_name_asc.label'))->setDesc('Sort by section A-Z'),
+            (new Message('sort_definition.section_name_desc.label'))->setDesc('Sort by section Z-A'),
+        ];
+    }
+}

code_samples/back_office/search/translations/messages.en.yaml

@@ -0,0 +1,2 @@
+sort_definition.section_name_asc.label: 'Sort by section A-Z'
+sort_definition.section_name_desc.label: 'Sort by section Z-A'

docs/administration/back_office/customize_search_sorting.md

@@ -0,0 +1,34 @@
+---
+description: Add a "sort by" method to the Back Office search result page.
+---
+
+# Customize search sorting
+
+You can customize the **Sort by** menu in the Back Office search result page, for example, by adding new sort criteria.
+
+To do it, you must create a service that implements the `Ibexa\Contracts\Search\SortingDefinition\SortingDefinitionProviderInterface` and tag it with `ibexa.search.sorting_definition.provider`.
+
+The following example class implements `SortingDefinitionProviderInterface::getSortingDefinitions`, and adds two definitions to sort by section name.
+A sorting definition contains an identifier, a menu label, a list of content search Sort Clauses, which could be either [default](sort_clause_reference.md#sort-clauses) or [custom](create_custom_sort_clause.md), and a priority value to position them in the menu.
+It also implements `TranslationContainerInterface::getTranslationMessages` to provide two default English translations in the `ibexa_search` namespace.
+
+Create the `src/Search/SortingDefinition/Provider/SectionNameSortingDefinitionProvider.php` file:
+
+``` php hl_lines="22"
+[[= include_file('code_samples/back_office/search/src/Search/SortingDefinition/Provider/SectionNameSortingDefinitionProvider.php') =]]
+```
+
+Then add a service definition to `config/services.yaml`:
+
+``` yaml hl_lines="5"
+services:
+    #…
+[[= include_file('code_samples/back_office/search/config/append_to_services.yaml', 29, 32) =]]
+```
+
+You can extract a translation file with the `translation:extract` command, for example, `php bin/console translation:extract en --dir=src --output-dir=translations` to obtain the `translations/ibexa_search.en.xlf` file.
+You could also create it manually, as `translations/messages.en.yaml` file with the following contents:
+
+``` yaml
+[[= include_file('code_samples/back_office/search/translations/messages.en.yaml') =]]
+```

docs/administration/back_office/customize_search_suggestion.md

@@ -139,7 +139,7 @@ To be present, this wrapping node template must be added to the `global-search-a
 ``` yaml
 services:
     #…
-[[= include_file('code_samples/back_office/search/config/append_to_services.yaml', 22, 28) =]]
+[[= include_file('code_samples/back_office/search/config/append_to_services.yaml', 21, 28) =]]
 ```
 
 The template for the product suggestion item follows, named `templates/themes/admin/ui/global_search_autocomplete_product_item.html.twig`:

mkdocs.yml

@@ -146,6 +146,7 @@ nav:
             - Sub-items list: administration/back_office/subitems_list.md
             - Notifications: administration/back_office/notifications.md
             - Customize search suggestion: administration/back_office/customize_search_suggestion.md
+            - Customize search sorting: administration/back_office/customize_search_sorting.md
     - Content management:
         - Content management: content_management/content_management.md
         - Content management guide: content_management/content_management_guide.md
@@ -290,7 +291,7 @@ nav:
             - Storefront Twig functions: templating/twig_function_reference/storefront_twig_functions.md
             - URL Twig functions: templating/twig_function_reference/url_twig_functions.md
             - User Twig functions: templating/twig_function_reference/user_twig_functions.md
-            - Other Twig filters: templating/twig_function_reference/other_twig_filters.md    
+            - Other Twig filters: templating/twig_function_reference/other_twig_filters.md
         - URLs and routes:
             - URLs and routes: templating/urls_and_routes/urls_and_routes.md
             - Custom breadcrumbs: templating/urls_and_routes/custom_breadcrumbs.md