Skip to content
  • Documentation >
  • Administration >
  • Back office >
  • Customize search >
  • Customize search suggestion

Customize search suggestion

In the back office, when you start typing in the search field on the top bar, suggestions about what you could be looking for show up directly under the field. For more information about using this feature to search for content, see User Documentation.

Configuration

By default, suggestions start showing up after the user types in at least 3 characters, and 5 suggestions are presented. This can be changed with the following scoped configuration:

1
2
3
4
5
6
ibexa:
    system:
        <scope>:
            search:
                min_query_length: 3
                result_limit: 5

Add custom suggestion source

You can add a suggestion source by listening or subscribing to Ibexa\Contracts\Search\Event\BuildSuggestionCollectionEvent. During this event, you can add, remove, or replace suggestions by updating its SuggestionCollection. After this event, the suggestion collection is sorted by score and truncated to a number of items set in result_limit.

Tip

You can list listeners and subscribers with the following command:

1
php bin/console debug:event BuildSuggestionCollectionEvent

The following example is boosting product suggestions. It's a subscriber that passes after the default one (because priority is set to zero), adds matching products at a score above the earlier content suggestions, and avoids duplicates.

  • If the suggestion source finds a number of matching products that is equal or greater than the result_limit, only those products end up in the suggestion.
  • If it finds less than result_limit products, those products are on top of the suggestion, followed by items from another suggestion source until the limit is met.
  • If it doesn't find any matching products, only items from the default suggestion source are shown.

This example event subscriber is implemented in the src/EventSubscriber/MySuggestionEventSubscriber.php file. It uses ProductService::findProducts, and returns the received event after having manipulated the SuggestionCollection:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
<?php declare(strict_types=1);

namespace App\EventSubscriber;

use App\Search\Model\Suggestion\ProductSuggestion;
use Ibexa\Contracts\ProductCatalog\ProductServiceInterface;
use Ibexa\Contracts\ProductCatalog\Values\Product\ProductQuery;
use Ibexa\Contracts\ProductCatalog\Values\Product\Query\Criterion;
use Ibexa\Contracts\Search\Event\BuildSuggestionCollectionEvent;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerAwareTrait;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MySuggestionEventSubscriber implements EventSubscriberInterface, LoggerAwareInterface
{
    use LoggerAwareTrait;

    private ProductServiceInterface $productService;

    public function __construct(
        ProductServiceInterface $productService,
    ) {
        $this->productService = $productService;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            BuildSuggestionCollectionEvent::class => ['onBuildSuggestionCollectionEvent', -1],
        ];
    }

    public function onBuildSuggestionCollectionEvent(BuildSuggestionCollectionEvent $event): BuildSuggestionCollectionEvent
    {
        $suggestionQuery = $event->getQuery();
        $suggestionCollection = $event->getSuggestionCollection();

        $text = $suggestionQuery->getQuery();
        $words = explode(' ', preg_replace('/\s+/', ' ', $text));
        $limit = $suggestionQuery->getLimit();

        try {
            $productQuery = new ProductQuery(null, new Criterion\LogicalOr([
                new Criterion\ProductName(implode(' ', array_map(static function (string $word) {
                    return "$word*";
                }, $words))),
                new Criterion\ProductCode($words),
                new Criterion\ProductType($words),
            ]), [], 0, $limit);
            $searchResult = $this->productService->findProducts($productQuery);

            if ($searchResult->getTotalCount()) {
                $maxScore = 0.0;
                $suggestionsByContentIds = [];
                /** @var \Ibexa\Contracts\Search\Model\Suggestion\ContentSuggestion $suggestion */
                foreach ($suggestionCollection as $suggestion) {
                    $maxScore = max($suggestion->getScore(), $maxScore);
                    $suggestionsByContentIds[$suggestion->getContent()->id] = $suggestion;
                }

                /** @var \Ibexa\ProductCatalog\Local\Repository\Values\Product $product */
                foreach ($searchResult as $product) {
                    $contentId = $product->getContent()->id;
                    if (array_key_exists($contentId, $suggestionsByContentIds)) {
                        $suggestionCollection->remove($suggestionsByContentIds[$contentId]);
                    }

                    $productSuggestion = new ProductSuggestion($maxScore + 1, $product);
                    $suggestionCollection->append($productSuggestion);
                }
            }
        } catch (\Throwable $throwable) {
            $this->logger->error($throwable);
        }

        return $event;
    }
}

To have the logger injected thanks to the LoggerAwareTrait, this subscriber must be registered as a service:

1
2
3
services:
    #…
    App\EventSubscriber\MySuggestionEventSubscriber: ~

To represent the product suggestion data, a ProductSuggestion class is created in src/Search/Model/Suggestion/ProductSuggestion.php:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?php declare(strict_types=1);

namespace App\Search\Model\Suggestion;

use Ibexa\Contracts\Search\Model\Suggestion\Suggestion;
use Ibexa\ProductCatalog\Local\Repository\Values\Product;

class ProductSuggestion extends Suggestion
{
    private Product $product;

    public function __construct(
        float $score,
        Product $product
    ) {
        parent::__construct($score, $product->getName());
        $this->product = $product;
    }

    public function getProduct(): Product
    {
        return $this->product;
    }
}

This representation needs a normalizer to be transformed into a JSON. ProductSuggestionNormalizer::supportsNormalization returns that this normalizer supports ProductSuggestion. ProductSuggestionNormalizer::normalize returns an array of scalar values which can be transformed into a JSON object. Alongside data about the product, this array must have a type key, whose value is used later for rendering as an identifier. In src/Search/Serializer/Normalizer/Suggestion/ProductSuggestionNormalizer.php:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?php declare(strict_types=1);

namespace App\Search\Serializer\Normalizer\Suggestion;

use App\Search\Model\Suggestion\ProductSuggestion;
use Symfony\Component\Serializer\Normalizer\CacheableSupportsMethodInterface;
use Symfony\Component\Serializer\Normalizer\NormalizerAwareInterface;
use Symfony\Component\Serializer\Normalizer\NormalizerAwareTrait;
use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

class ProductSuggestionNormalizer implements
    NormalizerInterface,
    NormalizerAwareInterface,
    CacheableSupportsMethodInterface
{
    use NormalizerAwareTrait;

    public function normalize($object, string $format = null, array $context = [])
    {
        /** @var \App\Search\Model\Suggestion\ProductSuggestion $object */
        return [
            'type' => 'product',
            'name' => $object->getName(),
            'productCode' => $object->getProduct()->getCode(),
            'productTypeIdentifier' => $object->getProduct()->getProductType()->getIdentifier(),
            'productTypeName' => $object->getProduct()->getProductType()->getName(),
        ];
    }

    public function supportsNormalization($data, string $format = null)
    {
        return $data instanceof ProductSuggestion;
    }

    public function hasCacheableSupportsMethod(): bool
    {
        return true;
    }
}

This normalizer is added to suggestion normalizers by decorating ibexa.search.suggestion.serializer and redefining its list of normalizers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
services:
    #…
    App\Search\Serializer\Normalizer\Suggestion\ProductSuggestionNormalizer:
        autoconfigure: false

    app.search.suggestion.serializer:
        decorates: ibexa.search.suggestion.serializer
        class: Symfony\Component\Serializer\Serializer
        autoconfigure: false
        arguments:
            $normalizers:
                - '@App\Search\Serializer\Normalizer\Suggestion\ProductSuggestionNormalizer'
                - '@Ibexa\Search\Serializer\Normalizer\Suggestion\ContentSuggestionNormalizer'
                - '@Ibexa\Search\Serializer\Normalizer\Suggestion\LocationNormalizer'
                - '@Ibexa\Search\Serializer\Normalizer\Suggestion\ParentLocationCollectionNormalizer'
                - '@Ibexa\Search\Serializer\Normalizer\Suggestion\SuggestionCollectionNormalizer'
            $encoders:
                - '@serializer.encoder.json'

Tip

At this point, it's possible to test the suggestion JSON. The route is /suggestion with a GET parameter query for the searched text.

For example, log in to the back office to have a session cookie, then access the route through the back office SiteAccess, such as <yourdomain>/admin/suggestion?query=platform. If you have a product with "platform" in its name, it is returned as the first suggestion.

A JavaScript renderer displays the normalized product suggestion. This renderer is wrapped in an immediately executed function. This wrapping function must define a rendering function and register it as a renderer. It's registered as autocomplete.renderers.<type> by using the type identifier defined in the normalizer.

1
2
3
4
5
6
7
 (function (global, doc, ibexa, Routing) {
     const renderItem = (result, searchText) => {
         // Compute suggestion item's HTML
         return html;
     }
    ibexa.addConfig('autocomplete.renderers.<type>', renderItem, true);
 })(window, document, window.ibexa, window.Routing);

To fit into the back office design, you can take HTML structure and CSS class names from an existing suggestion template vendor/ibexa/admin-ui/src/bundle/Resources/views/themes/admin/ui/global_search_autocomplete_content_item.html.twig.

To allow template override and ease HTML writing, the example is also loading a template to render the HTML.

Here is a complete assets/js/admin.search.autocomplete.product.js from the product suggestion example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
(function (global, doc, ibexa, Routing) {
    const renderItem = (result, searchText) => {
        const globalSearch = doc.querySelector('.ibexa-global-search');
        const {highlightText} = ibexa.helpers.highlight;
        const autocompleteHighlightTemplate = globalSearch.querySelector('.ibexa-global-search__autocomplete-list').dataset.templateHighlight;
        const {getContentTypeIconUrl, getContentTypeName} = ibexa.helpers.contentType;

        const autocompleteItemTemplate = globalSearch.querySelector('.ibexa-global-search__autocomplete-product-template').dataset.templateItem;

        return autocompleteItemTemplate
            .replace('{{ productHref }}', Routing.generate('ibexa.product_catalog.product.view', {productCode: result.productCode}))
            .replace('{{ productName }}', highlightText(searchText, result.name, autocompleteHighlightTemplate))
            .replace('{{ productCode }}', result.productCode)
            .replace('{{ productTypeIconHref }}', getContentTypeIconUrl(result.productTypeIdentifier))
            .replace('{{ productTypeName }}', result.productTypeName);
    };

    ibexa.addConfig('autocomplete.renderers.product', renderItem, true);
})(window, document, window.ibexa, window.Routing);

To be loaded in the back office layout, this file must be added to Webpack entry ibexa-admin-ui-layout-js. At the end of webpack.config.js, add it by using ibexaConfigManager:

1
2
3
4
5
6
7
8
9
//…

const ibexaConfigManager = require('./ibexa.webpack.config.manager.js');

ibexaConfigManager.add({
    ibexaConfig,
    entryName: 'ibexa-admin-ui-layout-js',
    newItems: [ path.resolve(__dirname, './assets/js/admin.search.autocomplete.product.js'), ],
});

The renderer, renderItem function from admin.search.autocomplete.product.js, loads an HTML template from a wrapping DOM node dataset. This wrapping node exists only once and the renderer loads the template several times.

The example template for this wrapping node is stored in templates/themes/admin/ui/global_search_autocomplete_product_template.html.twig (notice the CSS class name used by the renderer to reach it):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<div
    class="ibexa-global-search__autocomplete-product-template"
    data-template-item="{{ include('@ibexadesign/ui/global_search_autocomplete_product_item.html.twig', {
        product_href: "{{ productHref }}",
        product_name: "{{ productName }}",
        product_code: "{{ productCode }}",
        product_type_icon_href: "{{ productTypeIconHref }}",
        product_type_name: "{{ productTypeName }}"
    })|e('html_attr') }}">
</div>
  • At HTML level, it wraps the product item template in its dataset attribute data-template-item.
  • At Twig level, it includes the item template, replaces Twig variables with the strings used by the JS renderer, and passes it to the escape filter with the HTML attribute strategy.

To be present, this wrapping node template must be added to the global-search-autocomplete-templates group of tabs components:

1
2
3
4
5
6
7
8
9
services:
    #…
    ibexa.search.autocomplete.product_template:
        parent: Ibexa\AdminUi\Component\TabsComponent
        arguments:
            $template: '@@ibexadesign/ui/global_search_autocomplete_product_template.html.twig'
            $groupIdentifier: 'global-search-autocomplete-product'
        tags:
            - { name: ibexa.admin_ui.component, group: global-search-autocomplete-templates }

The template for the product suggestion item follows, named templates/themes/admin/ui/global_search_autocomplete_product_item.html.twig:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
<li class="ibexa-global-search__autocomplete-item">
    <a class="ibexa-global-search__autocomplete-item-link ibexa-link" href="{{ product_href }}">
        <div class="ibexa-global-search__autocomplete-item-name">
            {{ product_name }}
            <div class="ibexa-badge">
                {{ product_code }}
            </div>
        </div>
        <div class="ibexa-global-search__autocomplete-item-info">
            <div class="ibexa-global-search__autocomplete-item-content-type-wrapper">
                <svg class="ibexa-icon ibexa-icon--tiny-small">
                    <use xlink:href="{{ product_type_icon_href }}"></use>
                </svg>
                <span  class="ibexa-global-search__autocomplete-item-content-type">
                    {{ product_type_name }}
                </span>
            </div>
        </div>
    </a>
</li>

Replace default suggestion source

To replace the default suggestion source, decorate the built-in BuildSuggestionCollectionEvent subscriber with your own:

1
2
3
4
services:
    #…
    App\EventSubscriber\MySuggestionEventSubscriber:
        decorates: Ibexa\Search\EventDispatcher\EventListener\ContentSuggestionSubscriber