README

此软件包为Contao CMS提供Choices.js JavaScript库的支持。

特性

• 在页面级别激活choices支持（带有继承和覆盖选项）
• 从dca自定义选项或从事件动态自定义
• Encore Bundle支持
• Filter Bundle支持

设置

1. 使用composer安装： composer require heimrichhannot/contao-choices-bundle。
2. 更新数据库
3. Encore Bundle：准备和生成encore条目

使用方法

在页面级别激活或停用choices支持（布局部分）。您可以分别为下拉框和文本框单独激活/停用。您可以覆盖父页面的设置。

还可以为单个字段激活和停用choices支持。

使用DCA配置

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

使用CustomizeChoicesOptionsEventListener

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

注意：如果已在页面级别激活，则默认启用choices。

配置

可以通过DCA自定义每个字段

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

所有Choices.js选项可以在https://github.com/Choices-js/Choices#setup找到

注意：唯一不是来自choices.js的选项是'enable' => true|false

Filter Bundle

Choices.js自动将其支持添加到选择类型表单字段。它可以在类型配置中禁用。对于其他配置类型，它可以在配置中激活。

开发者

PHP事件

要自定义传递给choices.js库的选项，您可以使用CustomizeChoicesOptionsEvent。将事件监听器注册到huh.choices.customize_choices_options。这适用于'正常'小部件和filter bundle字段。在您的事件监听器中，通过调用CustomizeChoicesOptionsEvent::isFilterField(): bool检查事件是否来自filter bundle字段。在这种情况下，传递的是完整的（但已克隆的）AdjustFilterOptionsEvent，而fieldAttributes数组为空。如果您不使用filter bundle，则可以忽略filter bundle部分。

  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事件

可以使用以下事件进一步自定义choices实例

示例

/**
 * @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);

自定义使用

如果您以不同于此软件包提供的方式使用库（例如自定义模块），请使用前端资产服务动态添加前端资产。

use HeimrichHannot\ChoicesBundle\Asset\FrontendAsset;

class MyClass 
{
    private FrontendAsset $frontendAsset;

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