README

为 SilverStripe v4 提供由 Select2 驱动的下拉和 Ajax 字段。旨在与 SilverStripe v4 一起使用，但此模块也可以安装到常规的 SilverStripe v4 项目中。

内容

• 要求
• 安装
• 配置
• 使用
• 问题
• 贡献
• 归属
• 维护者
• 许可

要求

• SilverStripe Framework v4

安装

安装通过 Composer 完成。

$ composer require silverware/select2

配置

与所有 SilverStripe 模块一样，配置通过 YAML 完成。通过 config.yml 应用对 LeftAndMain 的扩展。

使用

Select2Field

Select2Field 类与常规的 DropdownField 使用方式完全相同。

use SilverWare\Select2\Forms\Select2Field;

$field = Select2Field::create(
  'MySelect2Field',
  'Select2 Field',
  [
    1 => 'An',
    2 => 'Array',
    3 => 'of',
    4 => 'Options'
  ]
);

Select2 配置

您可以使用 setConfig() 方法定义 Select2 配置设置中的任何一项。

$field->setConfig('maximum-input-length', 20);

或者，您可以使用 YAML 配置为您的应用中的所有 Select2Field 实例设置默认值。

SilverWare\Select2\Forms\Select2Field:
  default_config:
    maximum-input-length: 20

注意：配置设置名称使用 HTML 属性样式定义，而不是驼峰式命名，例如

$field->setConfig('maximum-input-length', 20);  // this will work
$field->setConfig('maximumInputLength', 20);    // this will NOT work

Select2AjaxField

Select2AjaxField 用于根据用户输入的搜索词搜索 DataList。结果通过 Ajax 从服务器获取并作为下拉选项渲染。这对于常规下拉列表中可用的选项数量非常多的情况非常有用。

字段创建方式与其他任何字段一样。

use SilverWare\Select2\Forms\Select2AjaxField;

$field = Select2AjaxField::create(
  'MySelect2AjaxField',
  'Select2 Ajax Field'
);

但是，我们不向构造函数传递一个包含可选项的数组。相反，我们配置字段在服务器端搜索 DataList。以下是一些默认设置

$field->setDataClass(SiteTree::class);  // by default, the field searches for SiteTree records

$field->setIDField('ID');       // the name of the field which identifies the record
$field->setTextField('Title');  // the name of the field to use for the option text

$field->setSearchFields([
  'Title'  // an array of fields to search based on the entered term
]);

$field->setSortBy([
  'Title' => 'ASC'  // an array which defines the sort order of the results
]);

$field->setLimit(256);  // the maximum number of records to return

如前所述，这些都是默认设置，并且该字段对于 SiteTree 搜索将直接工作。

排除项

您还可以定义一系列排除过滤器，这些过滤器使用与 DataList 的 exclude 方法相同的格式。

$field->setExclude([
  'Title:ExactMatch' => 'Hide This Title'
]);

任何匹配定义的排除过滤器的记录都将从结果中排除。

格式化

默认情况下，字段将根据匹配记录的 $ID 和 $Title 渲染一系列常规的下拉选项，但是您可以应用更高级的格式化来处理结果和当前选择。例如

$field->setFormatResult('<span>Found: <em>$Title</em></span>');
$field->setFormatSelection('<span>Selected: <strong>$Title</strong></span>');

HTML 将作为 jQuery 对象渲染，所以请确保将其包裹在一个封闭元素（如 <span>）中。

Ajax 配置

可以使用 setAjaxConfig() 方法定义任何 Select2 Ajax 设置。

$field->setAjaxConfig('cache', false);
$field->setAjaxConfig('delay', 500);

或者，您可以使用 YAML 配置为您的应用中的所有 Select2AjaxField 实例设置默认值。

SilverWare\Select2\Forms\Select2AjaxField:
  default_ajax_config:
    cache: false
    delay: 500

注意：配置设置名称使用 HTML 属性样式定义，而不是驼峰式命名，例如

$field->setAjaxConfig('data-type', 'json');  // this will work
$field->setAjaxConfig('dataType', 'json');   // this will NOT work

问题

请使用 GitHub 问题跟踪器 提交错误报告和功能请求。

贡献

我们非常欢迎您的贡献，以帮助使此项目变得更好。请参阅 贡献 了解更多信息。

归属

• 使用了由Kevin Brown、Igor Vaynberg以及其他贡献者共同开发的Select2。

维护者

许可

BSD-3-Clause © Praxis Interactive