heimrichhannot/contao-choices-bundle

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

1.5.4 2024-03-21 14:29 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.196
• psr/container: ^1.0 || ^2.0
• symfony/dependency-injection: ^4.4 || ^5.4
• symfony/event-dispatcher-contracts: ^1.0 || ^2.0 || ^3.0
• symfony/service-contracts: ^1.0 || ^2.0 || ^3.0

Suggests

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

LGPL-3.0-or-later

README

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

Features

• activate choices support on page level (with inheritance and override option)
• customize options from dca or dynamically from event
• Encore Bundle support
• Filter Bundle support

Setup

1. Install via composer: composer require heimrichhannot/contao-choices-bundle.
2. Update Database
3. Encore Bundle: Prepare and generate encore entries

Usage

Active or deactivate choices support on page level (Layout section). You can activate/deactivate it separately for select and text boxes. You can overwrite settings from a parent page.

It is possible to active and deactivate choices support for single field as well.

Using DCA configuration:

['field']['eval']['choicesOptions'] = [
    'enable' => true|false
];

Using CustomizeChoicesOptionsEventListener

public function onHuhChoicesCustomizeChoicesOptions(CustomizeChoicesOptionsEvent $event)
{
    $event->enableChoices();
    $event->disableChoices();
}

NOTE: Choices are enabled by default if activated on page level.

Configuration

Each field can be customized via DCA:

['field']['eval']['choicesOptions'] = [];

All options from Choices.js can be found at https://github.com/Choices-js/Choices#setup

NOTE: the only option not from choices.js is 'enable' => true|false

Filter Bundle

Choices.js support it automatically added to choice type form fields. It can be disabled in the type configuration. For other config types it can be activated in the configuration.

Developers

PHP Events

To customize options passed to the choices.js library, you can use the CustomizeChoicesOptionsEvent. Register an event listener to huh.choices.customize_choices_options. This work for 'normal' widgets and filter bundle fields. In your event listener you check, if the event comes from an filter bundle field by calling CustomizeChoicesOptionsEvent::isFilterField(): bool. In this case, the complete (but cloned) AdjustFilterOptionsEvent is passed to the event and the fieldAttributes array is empty. If you don't use filter bundle, you can ignore the filter bundle part.

  HeimrichHannot\CustomBundle\EventListener\CustomizeChoicesOptionsListener:
    tags:
      - { name: kernel.event_listener, event: huh.choices.customize_choices_options }

use HeimrichHannot\ChoicesBundle\Event\CustomizeChoicesOptionsEvent;

class CustomizeChoicesOptionsListener
{
    public function __invoke(CustomizeChoicesOptionsEvent $event)
    {
        if ($event->isFilterField()) {
            $this->addFilterChoicesOptions($event);
        } else {
            $this->addFieldChoicesOptions($event);
        }       
    }
}

JavaScript Events

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

Example:

/**
 * @param { CustomEvent } event
 */
function onHundhChoicesOptions(event) {
    let options = event.detail.options;
    // Customize options
}

/**
 * @param { CustomEvent } event
 */
function onHundhChoicesNewInstance(event) {
    let choicesInstance = event.detail.instance;
    // Work with the choices instance
}

document.addEventListener('hundhChoicesOptions', onHundhChoicesOptions);
document.addEventListener('hundhChoicesNewInstance', onHundhChoicesNewInstance);

Custom usage

If you use the library in a different way than this bundle provides (e.g. a custom module), use the frontend asset service to dynamically add the frontend assets.

use HeimrichHannot\ChoicesBundle\Asset\FrontendAsset;

class MyClass 
{
    private FrontendAsset $frontendAsset;

    public function action() {
        $this->frontendAsset->addFrontendAssets();
    }
}