IBX-6878: Customize search sorting

code_samples/back_office/search/config/append_to_services.yaml

@@ -0,0 +1,5 @@
+services:
+
+    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/search_sorting.md

@@ -0,0 +1,26 @@
+---
+description: Add a "sort by" method to the Back Office search result page.
+---
+
+# Customize search sorting
+
+To add an entry to the "Sort by" to the Back Office search result page, create a service to implement the `Ibexa\Contracts\Search\SortingDefinition\SortingDefintionProviderInterface` and tag `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's Sort Clauses](sort_clause_reference.md#sort-clauses), including [custom ones](create_custom_sort_clause.md), and a priority to position it in the menu.
+It also implements `TranslationContainerInterface::getTranslationMessages` to provide two default English translations in the `ibexa_search` namespace.
+The example below is coded in `src/Search/SortingDefinition/Provider/SectionNameSortingDefinitionProvider.php`:
+``` php hl_lines="22"
+[[= include_file('code_samples/back_office/search/src/Search/SortingDefinition/Provider/SectionNameSortingDefinitionProvider.php') =]]
+```
+
+The service definition is added to `config/services.yaml`:
+``` yaml hl_lines="5"
+[[= include_file('code_samples/back_office/search/config/append_to_services.yaml') =]]
+```
+
+Translation file can be extracted with a `translation:extract` command, such as `php bin/console translation:extract en --dir=src --output-dir=translations` to obtain an `translations/ibexa_search.en.xlf` file.
+It can be also created manually, as `translations/messages.en.yaml` file below :
+``` yaml
+[[= include_file('code_samples/back_office/search/translations/messages.en.yaml') =]]
+```

mkdocs.yml

@@ -145,6 +145,7 @@ nav:
             - Multi-file upload: administration/back_office/multifile_upload.md
             - Sub-items list: administration/back_office/subitems_list.md
             - Notifications: administration/back_office/notifications.md
+            - Customize search sorting: administration/back_office/search_sorting.md
     - Content management:
         - Content management: content_management/content_management.md
         - Content management guide: content_management/content_management_guide.md