Quick filters for searches

Quick filters provide an efficient way to search using existing search commands. This documentation outlines how to create and implement new quick filters for Mautic searches.

Implementation overview

Mautic implements quick filters using a combination of JavaScript and Twig templates. The process involves three main components:

1. JavaScript function for applying the filter

2. Twig template for rendering filter buttons

3. Array of PHP code for defining filter options

JavaScript functionality

The Mautic.listQuickFilter function is responsible for applying the quick filter:

Mautic.listQuickFilter = function (element) {
    const filterValue = element.dataset.filter;
    const searchInput = document.getElementById('list-search');
    searchInput.value = filterValue;
    const enterKeyEvent = new KeyboardEvent('keyup', {
        keyCode: 13
    });
    searchInput.dispatchEvent(enterKeyEvent);
}

This function performs the following actions:

1. Retrieves the filter value from the clicked element’s data-filter attribute

2. Sets the search input field’s value to the filter value

3. Simulates an Enter key press to trigger the search

Twig template

Mautic renders the quick filter buttons using a Twig template:

{% if quickFilters is defined and quickFilters is not empty %}
<div class="d-flex gap-xs">
    {% for quickFilter in quickFilters %}
        <a class="label label-outline"
           data-filter="{{ quickFilter.search }}"
           onclick="Mautic.listQuickFilter(this)"
           data-toggle="tooltip"
           data-placement="top"
           data-original-title="{{ quickFilter.tooltip|trans }}">
            <i class="{{ quickFilter.icon }}"></i>
            {{ quickFilter.label|trans }}
        </a>
    {% endfor %}
</div>
{% endif %}

This template iterates through the provided quick filters and creates clickable labels for each one on the toolbar.

Implementing quick filters

To add quick filters to a list view, include the list_toolbar.html.twig template and pass the quickFilters option:

{{ include('@MauticCore/Helper/list_toolbar.html.twig', {
    'searchValue': searchValue,
    'searchHelp': 'mautic.form.form.help.searchcommands',
    'searchId': 'list-search',
    'action': currentRoute,
    'quickFilters': [
        {
            'search': 'has:results',
            'label': 'mautic.core.search.quickfilter.form_results',
            'tooltip': 'mautic.core.search.quickfilter.form_results.tooltip',
            'icon': 'ri-file-list-2-line'
        }
    ]
}) }}

Quick filter options

You define each quick filter as an associative array with the following keys:

• search: 要应用的搜索查询。

• label: 过滤器按钮上显示的文本。

• tooltip: 鼠标悬停时显示的工具提示文本。

• icon: 显示在按钮上的图标的 CSS 类。

多个快速过滤器

可以通过向 quickFilters 数组添加更多项来定义多个快速过滤器：

'quickFilters': [
    {
        'search': 'is:admin',
        'label': 'mautic.user.role.form.isadmin',
        'tooltip': 'mautic.core.search.quickfilter.is_admin',
        'icon': 'ri-admin-line'
    },
    {
        'search': 'is:published',
        'label': 'mautic.core.form.active',
        'tooltip': 'mautic.core.search.quickfilter.is_published',
        'icon': 'ri-check-line'
    },
    {
        'search': 'is:unpublished',
        'label': 'mautic.core.form.inactive',
        'tooltip': 'mautic.core.search.quickfilter.is_unpublished',
        'icon': 'ri-close-line'
    }
]