README

介绍

这是一个 Symfony 扩展包，它使得流行的 Select2 组件可以作为 Symfony 表单中标准实体字段的替代品使用。

它适用于 Symfony 4 和 5。对于 Symfony 2 和 3，请使用该扩展包的 2.x 版本。对于 Select2 4.0 及以上版本。对于旧版本，请使用该扩展包的 1.x 版本（与 Symfony 5 不兼容）。

与标准 Symfony 实体字段（使用 html select 渲染）相比，该扩展包提供的主要功能是通过远程 AJAX 调用检索列表。这意味着列表可以几乎无限大。唯一的限制是数据库查询或远程 Web 服务中检索数据的性能。

它适用于单选和多选。如果表单正在编辑一个 Symfony 实体，则这些模式与多对一和多对多关系相对应。在多选模式下，大多数人发现 Select2 用户界面比具有 multiple=true 的标准选择标签更容易使用，后者涉及使用 ctrl 键等不自然的操作。

该项目受到 lifo/typeahead-bundle 的启发，它使用 Bootstrap 2 中的 Typeahead 组件提供类似的功能。Select2Entity 可以在任何可以安装 Select2 的地方使用，包括 Bootstrap 3。

感谢 @ismailbaskin，我们现在有了 Select2 版本 4 的兼容性。

屏幕截图

这是一个展开的单选字段列表的表单。

这是一个展开的多选字段列表的表单。

安装

首先必须安装并使 Select2 正常工作。我希望设置一个演示网站，但我的设置基本上是 BraincraftedBootstrapBundle 与 Select2 一起安装用于 Bootstrap 3。一旦 Braincrafted 扩展包正常工作，我只需要安装以下文件

select2.js 和 select2.css 从 https://github.com/select2/select2/tree/4.0.0

select2-bootstrap.css 从 https://github.com/t0m/select2-bootstrap-css/tree/bootstrap3。这使它适用于 Bootstrap 3。

这些文件位于我的一个扩展包的 Resources/public/js 和 Resources/public/css 文件夹中，然后包含在我的主要 layout.html.twig 文件中。

或者，可以从 CloudFlare CDN 加载 select2.js 和 select2.css 的压缩版本，使用下面提供的两行代码： https://select2.github.io。确保脚本标签在 jQuery 加载后，可能在页面页脚。

• 将 tetranz/select2entity-bundle 添加到您项目的 composer.json 文件 "requires" 部分

{
    // ...
    "require": {
        // ...
        "tetranz/select2entity-bundle": "2.*"
    }
}

注意，这仅适用于 Select2 版本 4。如果您正在使用 Select2 版本 3.X，请使用 "tetranz/select2entity-bundle": "1.*" 在 composer.json 中

• 在您的项目根目录中运行 php composer.phar update tetranz/select2entity-bundle
• 更新您的项目 config/bundles.php 文件，并将此扩展包添加到 $bundles 数组中

$bundles = [
    // ...
    Tetranz\Select2EntityBundle\TetranzSelect2EntityBundle::class => ['all' => true]
];

• 更新您的项目 config/packages/twig.yaml 文件，以提供全局 twig 表单模板

twig:
    form_themes:
        - '@TetranzSelect2Entity/Form/fields.html.twig'

* Load the Javascript on the page. The simplest way is to add the following to your layout file. Don't forget to run console assets:install. Alternatively, do something more sophisticated with Assetic.

<script src="{{ asset('bundles/tetranzselect2entity/js/select2entity.js') }}"></script>

如何使用

以下内容适用于 Symfony 4。有关 Symfony 2/3 的配置和使用，请参阅 https://github.com/tetranz/select2entity-bundle/tree/v2.1

Select2Entity 使用简单。在一个表单类型类的 buildForm 方法中，将 Select2EntityType::class 指定为你原本使用 entity:class 的类型。

以下是一个示例

$builder
   ->add('country', Select2EntityType::class, [
            'multiple' => true,
            'remote_route' => 'tetranz_test_default_countryquery',
            'remote_params' => [], // static route parameters for request->query
            'class' => '\Tetranz\TestBundle\Entity\Country',
            'primary_key' => 'id',
            'text_property' => 'name',
            'minimum_input_length' => 2,
            'page_limit' => 10,
            'allow_clear' => true,
            'delay' => 250,
            'cache' => true,
            'cache_timeout' => 60000, // if 'cache' is true
            'language' => 'en',
            'placeholder' => 'Select a country',
            'query_parameters' => [
                'start' => new \DateTime(),
                'end' => (new \DateTime())->modify('+5d'),
                // any other parameters you want your ajax route request->query to get, that you might want to modify dynamically
            ],
            // 'object_manager' => $objectManager, // inject a custom object / entity manager 
        ])

将此代码放在文件顶部，与表单类型类一起

use Tetranz\Select2EntityBundle\Form\Type\Select2EntityType;

选项

如果没有设置，将使用默认值。

• class 是你的实体类。必需的
• primary_key 是用于唯一识别实体的属性的名称。默认为 'id'
• text_property 这是对现有数据进行文本检索所使用的实体属性。如果省略 text_property，则实体将被转换为字符串。这要求它必须有一个 __toString() 方法。
• multiple 对于多选（多对多）。对于单选（多对一）则为 False。
• minimum_input_length 是在搜索发生之前需要按下的键的数量。默认为 2。
• page_limit 这将被作为远程调用的查询参数传递。它旨在用于限制返回列表的大小。默认为 10。
• scroll True 将启用无限滚动。默认为 false。
• allow_clear True 将导致 Select2 显示一个小的 x 来清除值。默认为 false。
• allow_add 是 Select2 添加标签设置的选项数组。仅在表单上 'multiple' 为 true 时可用。
  • enabled 启用允许新标签选项。True 或 False。默认为 False。
  • new_tag_text 如果 allow_add 为 true，则显示在不存在实体后面的文本。默认为 " (NEW)"。
  • new_tag_prefix 新标签的前缀标识符，默认为 "__"。你的实际值开头不得包含这些符号。
  • tag_separators 一个 JavaScript 分隔符数组，用于自动拆分标签。
• delay 在触发另一个 AJAX 请求之前，按键后的延迟（以毫秒为单位）。默认为 250 毫秒。
• placeholder 占位符文本。
• language i18n 语言代码。默认为 en。
• theme 默认为 'default'。
• cache 启用 AJAX 缓存。结果将针对每个 'term' 查询进行缓存。
• cache_timeout 缓存查询的持续时间（以毫秒为单位）。将设置设置为 0 将导致缓存永远不会超时 (60000 = 60 秒)
• transformer 如果需要以下描述的灵活性，则提供完全限定的自定义转换器类的名称。
• autostart 确定是否在文档 ready 时自动调用 select2 jQuery 代码。默认为 true，这提供了正常操作。
• width 如果不是 null，则设置 data-width 属性。默认为 null。
• class_type 可选值，将被添加到 AJAX 请求作为查询字符串参数。
• render_html 这将在 ['html'] 下渲染返回的结果。

远程查询的 URL 可以通过两种方式之一提供：remote_route 是 Symfony 路由。可以可选地指定 remote_params 以提供参数。或者，可以使用 remote_path 直接指定 URL。

当远程_params 需要动态更改时，可以使用 query_parameters。您可以使用 $('#elem').data('query-parameters', { /* 新参数 */ }); 来更改它们。

可以在您的 config/packages/tetranzselect2entity.yaml 文件中更改默认值，格式如下。

tetranz_select2_entity:
    minimum_input_length: 2
    page_limit: 8
    allow_clear: true
    delay: 500
    language: 'fr'
    theme: 'default'
    cache: false
    cache_timeout: 0
    scroll: true
    object_manager: 'manager_alias'
    render_html: true

AJAX 响应

控制器应返回一个符合以下格式的 JSON 数组。属性必须是 id 和 text。

[
  { id: 1, text: 'Displayed Text 1' },
  { id: 2, text: 'Displayed Text 2' }
]

无限滚动

如果您的结果是通过Select2的“无限滚动”功能分页的，那么您可以选择继续返回上面显示的相同数组（为了向后兼容，此包将自动尝试确定是否需要更多结果），或者您可以选择返回下面的对象以对分页结果有更精细的控制。

如果还有更多结果要加载，则more字段应为true。

{
  results: [
     { id: 1, text: 'Displayed Text 1' },
     { id: 2, text: 'Displayed Text 2' }
  ],
  more: true
}

获取结果的控制器操作将接收到一个表示应加载哪些结果的页码的参数page。如果您将滚动设置为true，则必须在查询中处理页码参数。如果不这样做，会发生奇怪的事情。

自定义选项文本

如果您需要更灵活地显示每个选项的文本，例如显示实体中的几个字段的值或在其中显示图像，您可能需要定义自己的自定义转换器。您的转换器必须实现DataTransformerInterface。最简单的方法可能是扩展EntityToPropertyTransformer或EntitiesToPropertyTransformer并重新定义transform()方法。这样，您可以将任何内容作为text返回，而不仅仅是单个实体属性。

以下是一个返回国家名称和大洲（Country实体中的两个不同属性）的示例

$builder
    ->add('country', Select2EntityType::class, [
        'multiple' => true,
        'remote_route' => 'tetranz_test_default_countryquery',
        'class' => '\Tetranz\TestBundle\Entity\Country',
        'transformer' => '\Tetranz\TestBundle\Form\DataTransformer\CountryEntitiesToPropertyTransformer',
    ]);

在transform中设置数据数组如下

$data[] = array(
    'id' => $country->getId(),
    'text' => $country->getName().' ('.$country->getContinent()->getName().')',
);

您的自定义转换器和相应的Ajax控制器应返回以下格式的数组

[ 
    { id: 1, text: 'United Kingdom (Europe)' },
    { id: 1, text: 'China (Asia)' }
]

如果您正在使用allow_add选项并且实体需要除text_property字段以外的其他字段才有效，您可能需要扩展EntitiesToPropertyTransformer以添加缺少的字段，创建doctrine prePersist监听器，或者在提交表单后保存之前在表单视图中添加缺少的数据。

添加新标签

如果您想要能够通过Select2标签创建新实体，可以通过设置allow_add选项集来启用它。

例如

$builder
    ->add('tags', Select2EntityType::class, [
        'remote_route' => 'tetranz_test_tags',
        'class' => '\Tetranz\TestBundle\Entity\PostTags',
        'text_property' => 'name',
        'multiple' => true,
        'allow_add' => [
            'enabled' => true,
            'new_tag_text' => ' (NEW)',
            'new_tag_prefix' => '__',
            'tag_separators' => '[",", " "]'
        ],
    ]);

在添加标签时需要注意以下几点

• 您的数据不应有任何机会与new_tag_prefix的第一个字符匹配。如果有这种可能性，请将其更改为其他内容，如'**'或'$$'。
• tag_separators与Select2选项相同。它应该是一个JavaScript数组。
• 如果您想allow_add允许的实体除了在text_property中指定的字段外还有其他必填字段，您必须在表单提交中添加它们或添加到doctrine实体的prePersist钩子中。
• 如果您正在使用“tags”通过单条输入模式创建新实体，请注意您需要删除空格作为分隔符，否则您将无法输入该实体的空格字符。

$builder
    ->add('tags', Select2EntityType::class, [
        ...
        'allow_add' => [
            ...
            'tag_separators' => '[",", ""]' // No Space here
        ],
    ]);

包含其他字段值

如果您需要包含其他字段值，因为选择取决于它们，您可以添加req_params选项。键是查询字符串中参数的名称，值是FormView中的路径（如果您不知道路径，您可以在模板中执行类似{{ dump(form) }}的操作）。

property选项指的是您用于标签和搜索术语的实体字段。

在回调中，您将获得用于修改结果查询和数据对象的QueryBuilder参数（数据可以是简单的Request对象或纯数组。有关更多详细信息，请参阅AutocompleteService.php）。

$builder
    ->add('firstName', TextType::class)
        ->add('lastName', TextType::class)
        ->add('state', EntityType::class, array('class' => State::class))
        ->add('county', Select2EntityType::class, [
            'required' => true,
            'multiple' => false,
            'remote_route' => 'ajax_autocomplete',
            'class' => County::class,
            'minimum_input_length' => 0,
            'page_limit' => 10,
            'scroll' => true,
            'allow_clear' => false,
            'req_params' => ['state' => 'parent.children[state]'],
            'property' => 'name',
            'callback'    => function (QueryBuilder $qb, $data) {
                $qb->andWhere('e.state = :state');

                if ($data instanceof Request) {
                    $qb->setParameter('state', $data->get('state'));
                } else {
                    $qb->setParameter('state', $data['state']);
                }

            },
        ])
    ->add('city', Select2EntityType::class, [
        'required' => true,
        'multiple' => false,
        'remote_route' => 'ajax_autocomplete',
        'class' => City::class,
        'minimum_input_length' => 0,
        'page_limit' => 10,
        'scroll' => true,
        'allow_clear' => false,
        'req_params' => ['county' => 'parent.children[county]'],
        'property' => 'name',
        'callback'    => function (QueryBuilder $qb, $data) {
            $qb->andWhere('e.county = :county');

            if ($data instanceof Request) {
                $qb->setParameter('county', $data->get('county'));
            } else {
                $qb->setParameter('county', $data['county']);
            }

        },
    ]);

由于请求处理通常非常相似，您可以使用一个帮助您处理结果的服务。要使用它，只需在您的控制器中添加一个路由即可。

    /**
     * @param Request $request
     *
     * @Route("/autocomplete", name="ajax_autocomplete")
     *
     * @return Response
     */
    public function autocompleteAction(Request $request)
    {
        // Check security etc. if needed
    
        $as = $this->get('tetranz_select2entity.autocomplete_service');

        $result = $as->getAutocompleteResults($request, YourFormType::class);

        return new JsonResponse($result);
    }

模板化

现在已将通用模板添加到捆绑包中。如果您需要在选择结果中渲染HTML代码，请将render_html选项设置为true，并在控制器中返回如下所示的数据

[ 
    { id: 1, text: 'United Kingdom (Europe)', html: '<img src="images/flags/en.png" />' },
    { id: 2, text: 'China (Asia)', html: '<img src="images/flags/ch.png">' }
]

[ 
    { id: 1, text: 'United Kingdom (Europe)', img: 'images/flags/en.png' },
    { id: 2, text: 'China (Asia)', img: 'images/flags/ch.png' }
]

$.fn.select2entityAjax = function(action) {
    var action = action || {};
    var template = function (item) {
        var img = item.img || null;
        if (!img) {
            if (item.element && item.element.dataset.img) {
                img = item.element.dataset.img;
            } else {
                return item.text;
            }
        }
        return $(
            '<span><img src="' + img + '" class="img-circle img-sm"> ' + item.text + '</span>'
        );
    };
    this.select2entity($.extend(action, {
        templateResult: template,
        templateSelection: template
    }));
    return this;
};
$('.select2entity').select2entityAjax();

    ->add('contry', Select2EntityType::class, [
        'remote_route' => 'country_select2_query',
        'autostart' => false,
    ])

{% block tetranz_select2entity_widget_select_option %}
    <option value="{{ label.id }}" selected="selected"
            {% for key, data in label %}
                {% if key not in ['id', 'text'] %} data-{{ key }}="{{ data }}"{% endif %}
            {% endfor %}>
        {{ label.text }}
    </option>
{% endblock %}

主题

Select2支持使用theme选项使用自定义主题，因此您可以将Select2的样式与您的应用程序的其他部分匹配。有关Bootstrap4主题，请参阅https://github.com/ttskch/select2-bootstrap4-theme

嵌入集合表单

如果您使用嵌入式集合表单和data-prototype在表单中添加新元素，您将需要以下JavaScript，该JavaScript将监听添加元素.select2entity

$('body').on('click', '[data-prototype]', function(e) {
    $(this).prev().find('.select2entity').last().select2entity();
});