heimrichhannot/contao-autocompletejs-bundle

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

0.3.13 2024-04-05 09:00 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

Option name	Type	Value
data	Array	type, url, key, cache
data.url	String	url to be fetched for data
data.src	Array	array of values if autocomplete options are static values
data.keys	Array	keys of the data array if available
data.cache	Boolean	cache the input, must be 'false' if data.type is a function
searchEngine	String	'strict', 'loose' or 'none'
placeHolder	String	placeholder of the input field
selector	String	id of the input field
threshold	Integer	minimum number of characters to trigger autocomplete
debounce	Integer	idle time after entering new character (milliseconds)
maxResults	Integer	maximum number of results shown in the dropdown menu
highlight	Boolean	show entered characters in the results dropdown menu

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)

Events

Event name	Description
CustomizeAutocompletejsOptionsEvent	Used to modify options provided from dca

JavaScript Events

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

Event name	Data	Description
huh.autocompletejs.adjust_result_item	field, item	Customize matched Item in the dropdown menu (resultItem configuration option of the autoComplete object)
huh.autocompletejs.onselection	source, data	Customize selection behavior of selected Item (onSelection configuration options of the autoComplete object)

!!!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"}
}