Add custom data to the search
Overview
When developing a customization that has a frequently visited entity listing you're able to make use of an interesting opportunity: You can enable the user to take a shortcut finding his desired entry using the global search.
There are two different ways how the global search works:
- Global search without type specification
- Typed global search
They only differ in the API they use and get displayed in a slightly different way.
Think twice about adding this shortcut because if every plugin adds their own search tag it gets cluttered.
Prerequisites
For this guide, it's necessary to have a running Shopware 6 instance and full access to both the files and a running plugin. See our plugin page guide to learn how to create your own plugins.
In addition, you need a custom entity to add to the search to begin with. Head over to the following guide to learn how to achieve that:
Support custom entity via search API
To support an entity in the untyped global search the definition in the symfony container needs the tag
shopware.composite_search.definition. The priority of the tag defines the order in the search order.The typed global search needs an instance of the JavaScript class
ApiService with the key of the entity in camelcase suffixed with Service. E.g. The service key is yourCustomSearchService when requesting a service for your_custom_search. Every entity definition gets automatically an instance in the injection container but can be overridden so there is no additional work needed.Support in the Administration UI
Add search tag
The search tag displays the entity type that is used in the typed search and is a clickable button to switch from the untyped to the typed search. In order to add the tag, a service decorator is used to add a type to the
searchTypeService:1
const { Application } = Shopware;
2
​
3
Application.addServiceProviderDecorator('searchTypeService', searchTypeService => {
4
searchTypeService.upsertType('foo_bar', {
5
entityName: 'foo_bar',
6
entityService: 'fooBarService',
7
placeholderSnippet: 'foo-bar.general.placeholderSearchBar',
8
listingRoute: 'foo.bar.index'
9
});
10
​
11
return searchTypeService;
12
});
Copied!
Let's take a closer look on how this decorator is used:
- The key and
entityNameis used as the same to change also existing types. - The
entityServiceis used for the typed search. - This service can be overridden with an own implementation for customization.
- The
placeholderSnippetis a translation key that is shown when no search term is entered. - The
listingRouteis used to show a link to continue the search in the module specific listing view.
Add the search result item
By default, the search bar does not know how to display the result items, so a current search request will not show any result. In order to declare a search result view the
sw-search-bar-item template has to be altered as seen below, starting with the template:<plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/sw-search-bar-item.html.twig
1
{% block sw_search_bar_item_cms_page %}
2
{% parent %}
3
​
4
<router-link v-else-if="type === 'foo_bar'"
5
v-bind:to="{ name: 'foo.bar.detail', params: { id: item.id } }"
6
ref="routerLink"
7
class="sw-search-bar-item__link">
8
{% block sw_search_bar_item_foo_bar_label %}
9
<span class="sw-search-bar-item__label">
10
<sw-highlight-text v-bind:searchTerm="searchTerm"
11
v-bind:text="item.name">
12
</sw-highlight-text>
13
</span>
14
{% endblock %}
15
</router-link>
16
{% endblock %}
Copied!
Here you see the changes in the
index.js file:<plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/index.js
1
import template from './sw-search-bar-item.html.twig';
2
​
3
Shopware.Component.override('sw-search-bar-item', {
4
template
5
})
Copied!
The
sw_search_bar_item_cms_page block is used as it is the last block, but it is not important which shopware type is extended as long as the vue else-if structure is kept working.Add custom show more results link
By default, the search bar tries to resolve to the registered listing route. If your entity can be searched externally you can edit the
sw-search-more-results or sw-search components as well:<plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/sw-search-more-results.html.twig
1
{% block sw_search_more_results %}
2
<template v-if="result.entity === 'foo_bar'">
3
There are so many hits.
4
<a :href="'https://my.erp.localhost/?q=' + searchTerm"
5
class="sw-search-bar-item__link"
6
target="_blank">
7
Look it directly up
8
</a>
9
in the ERP instead.
10
</template>
11
<template v-else>
12
{% parent %}
13
</template>
14
{% endblock %}
Copied!
See for the changes in the
index.js file below:<plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/index.js
1
import template from './sw-search-more-results.html.twig';
2
​
3
Shopware.Component.override('sw-search-more-results', {
4
template
5
})
Copied!
Potential pitfalls
In case of a tag with a technical name with a missing translation, proceed like this:
1
{
2
"global": {
3
"entities": {
4
"my_entity": "My entity | My entities"
5
}
6
}
7
}
Copied!
To change the color of the tag, or the icon in the untyped global search a module has to be registered with an entity reference in the module:
1
Shopware.Module.register('any-name', {
2
color: '#ff0000',
3
icon: 'default-basic-shape-triangle',
4
entity: 'my_entity',
5
})
Copied!
Last modified 18d ago