heimrichhannot/contao-autocompletejs-bundle

This bundle offers support for autocomplete.js for the Contao CMS.

0.3.17 2024-12-05 08:48 UTC

Requires

• php: ^7.4 || ^8.0
• ext-json: *
• contao/core-bundle: ^4.9
• heimrichhannot/contao-encore-contracts: ^1.0
• heimrichhannot/contao-utils-bundle: ^2.177
• symfony/deprecation-contracts: ^1.0 || ^2.0 || ^3.0
• symfony/event-dispatcher-contracts: ^1.0 || ^2.0 || ^3.0

Suggests

• heimrichhannot/contao-encore-bundle: Manage dependencies with Symfony Webpack Encore.

LGPL-3.0-or-later

• Heimrich & Hannot

README

This bundle offers support for the JavaScript library autoComplete.js for the Contao CMS.

Features

• activate autocompletejs support on page level (with inheritance and override option)
• customize options from dca
• Encore Contracts support

Installation

Install via composer: composer require heimrichhannot/contao-autocompletejs-bundle and update your database.

Usage

Active or deactivate autocompletejs support on page level (Layout section). You can overwrite settings from a parent page.

DCA configuration

To activate autocompletejs on a dca field add

Add autocompletejs configuration to the eval array of dca field :

    'fieldName' => [
        'eval' = [
            'autocompletejs' => [ 
                'active' => true,
                'options' => []
            ]
        ]
    ]

Example: load data from an API

    'fieldName' => [
        'eval' = [
            'autocompletejs' => [ 
                'active' => true,
                'options' => [
                    'data' => [
                        'url' => 'https://example.org/users/{query}',
                        'keys' => ['name', 'city'],
                    ]
                ]
            ]
        ]
    ]

Return value of the api must be an array of objects. The object keys defined in data.keys will be used to display the results.

[
    {
        "name": "John Doe",
        "city": "New York"
    },
    {
        "name": "Jane Doe",
        "city": "Los Angeles"
    }
]

Configuration options

You can also set all options of the library (see more).

Custom configuration values

This bundle has a new value for searchEngine option : 'none'

Set searchEngine : 'none' if no search algorithm should be applied to the result list. This comes handy if your results are allready searched(eg. result list from an API)

Styling

A number of custom css properties is available to style the autocompletejs dropdown menu.

The following properties define the overall theme of the dropdown menu and can be overridden for easy styling:

.root {
    --huh-autocomplete-clr-text: black;
    --huh-autocomplete-clr-bg: white;
    --huh-autocomplete-clr-bg-hover: whitesmoke;
    --huh-autocomplete-clr-border: var(--bs-primary, var(--huh-autocomplete-clr-text, black));
}

Take a look at autocomplete-bundle.scss for a list of all available css properties for further customization.

Events

JavaScript Events

Following events can be used to further customize the autocompletejs instances:

!!!Caution!!! Known limitations

When fetching data via Controller make sure returning array is numerically consecutive indexed. Or if key option is used the array should not be numerically indexed at all. The JSON should never looks like this:

{
    "0" : {"key" : "value"},
    "1" : {"key" : "value"},
    "3" : {"key" : "value"}
}