README

简介

这是一个Symfony包，它允许使用流行的 Select2 组件作为Symfony表单上标准实体字段的直接替换方案。

它仅适用于Symfony 7和PHP 8.2+。

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

它支持单选和多选。如果表单正在编辑一个Symfony实体，那么这些模式对应于一对多和多对多关系。在多选模式下，大多数人发现Select2用户界面比标准的多选select标签更易于使用，后者涉及到使用ctrl键等尴尬的操作。

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

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

屏幕截图

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

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

安装

首先必须安装并使Select2运行。我希望设置一个演示站点，但我的设置基本上是BraincraftedBootstrapBundle，用于Bootstrap 3，并安装Select2。一旦Braincrafted包运行，我唯一需要安装的文件是

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

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

这些文件位于我的一个包的 Resources/public/js 和 Resources/public/css 文件夹中，然后包含在我的主要布局.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，请在 composer.json 中使用 "tetranz/select2entity-bundle": "1.*"

• 在项目根目录中运行 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 对于多选（多对多）为 true。对于单选（多对一）为 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 seconds)
• transformer 如果需要下面描述的灵活性，请提供完全限定类名的自定义转换器。
• autostart 确定是否在文档准备好时自动调用 select2 jQuery 代码。默认为 true，提供正常操作。
• width 如果不为 null，则设置 data-width 属性。默认为 null。
• class_type 可选值，将被添加到 AJAX 请求的查询字符串参数中。
• render_html 这将在 ['html'] 下渲染你的结果。

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

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

可以在 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数组。
• 如果你想要允许添加的实体除了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 代码，该代码将监听添加 .select2entity 元素的事件

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