README

适用于大型结构化选项集的选择小部件。

DCA中的使用

输入类型令牌: selectri

评估参数

值检索

小部件的选择值的标准表示形式是数组，将所选节点的键映射到包含所选节点键的数组，在数组键 _key 上以及与所选节点相关联的附加数据。

如果您直接使用此小部件，强烈建议您使用 getValue/setValue 方法，这将始终以这种标准表示形式返回值。

但是，如果您在 DCAs 中使用此小部件，则希望将小部件的 value 属性（由 DCA 使用）转换为特定的格式（在检索时）或从特定的格式转换（在设置时）。为了避免注册加载/保存回调，value 属性维护一个选中选项键的数组，或者如果设置了 max 为 1，则维护一个选中选项的键。对于常用的转换，存在以下 eval 属性以进一步修改 value 属性的内容

• findInSet - 布尔值 - 默认为 false

  • 获取: 返回选中选项键的逗号分隔列表。此行为优先于 canonical 设置。

  • 设置: 字符串被视为选中选项键的逗号分隔列表，并在 , 处分割。之后进行规范化。

• canonical - 布尔值 - 默认为 false

  • 获取: 返回选择的规范形式或，如果将 max 设置为 1，则仅返回选中选项的数据数组。

  • 设置: 进行规范化。

基本小部件配置

• min - 整数，非负 - 默认为 0

  至少必须选择多少个节点。

  如果 max 参数小于配置的最小值，则将 min 参数视为等于配置的最大值。

• max - 整数，正 - 默认为 1

  最多可以选择多少个节点。

• mandatory - 布尔值 - 可选 - 已弃用：应使用 min 参数

  如果给定并且为 true，则将 min 参数设置为 1，如果它已经不大于 0。如果给定并且为 false，则将 min 参数设置为 0。

• multiple - 布尔值 - 可选 - 已弃用：应使用 max 参数

  如果给定并且为 true，则将 max 参数设置为 PHP_INT_MAX，如果它已经不大于 1。如果给定并且为 false，则将 max 参数设置为 1。

• searchLimit - 整数，正 - 默认为 20

  从搜索中检索的最大节点数。

• sort - 字符串，之一 list、preorder、tree - 默认为 list

  所做选择的隐含结构

  • list: 选择是一个列表（顺序很重要），选择是可排序的
  • preorder 未实现: 选择是一组（顺序不重要），选择不可排序且按顺序排列
  • tree 未实现: 选择是一棵树，可以使用树属性对选择进行排列

• height - 字符串 - 默认为 auto

  选择树中 CSS height 属性的 CSS 值和单位。

• tl_class - 字符串 - 可选

  仅用于后端。

• class - 字符串 - 可选

  使用此功能安全地应用自定义 CSS。您可以使用 "radio" 或 "checkbox" 将 Contao 风格的选中 (+) 和取消选中 (x) 图标替换为类似 Windows 传统输入的图标图像。

• data - 字符串或实现 SelectriDataFactory 的对象 - 默认为字符串 SelectriContaoTableDataFactory

  如果提供了一个 对象 工厂，则这些工厂将被用于为创建的控件生成数据实例。不会调用 setParameters 方法。这是推荐提供 SelectriData 的方法，因为所有数据实现特定功能和选项都可以通过其工厂正确配置。

  如果提供了一个字符串，它必须指定一个实现 SelectriDataFactory 的类。在创建控件时，将创建一个新的工厂实例，并使用控件的属性（控件的属性包含 DCA 的 eval 数组中的所有设置）调用其 setParameters 方法。

工厂特定配置（由 data 参数中给出的 SelectriDataFactory 类的 setParameters 方法使用）

• treeTable - 字符串 - 可选

  要从其中获取树节点的表名。

  此参数由 SelectriContaoTableDataFactory::setParameters 方法使用，并根据常见的 Contao 标准（如主键列 id 和父键列 pid）预先配置数据。

• mode - 字符串 - 默认为 all

  此参数由 SelectriTableDataFactory::setParameters 方法使用。

  • all：所有节点都可选择
  • leaf：只有叶节点可选择
  • inner：只有内部节点可选择

在 DCA 中的简单使用示例

$GLOBALS['TL_DCA']['tl_mydca']['fields']['mySelectriField'] = array(
	...
	'inputType' => 'selectri',
	...
	'eval' => array(
    	// all values are the defaults
		'min'				=> 0,			// the selection can be empty
		'max'				=> 1,			// let the user select not more than 1 item
		'searchLimit'		=> 20,			// max search results
		'findInSet'			=> false,		// dont use csv
		'additionalInput'	=> false,		// no additional inputs via node content callback is injected
		'sort'				=> 'list',
		'height'			=> 'auto',		// the height of the tree widget
		'tl_class'			=> 'clr',		// some css-classes,
		'class'				=> '',			// use "radio" or "checkbox" to replace the icons
		'data'				=> 'SelectriContaoTableDataFactory', // the data factory class to use
		'treeTable'			=> 'tl_page',	// a DB-table containing the tree structure (Contao-like adjacency list)
		'mode'				=> 'all',		// which nodes are selectable: "all", "leaf", "inner"
	),
	...
);

在 DCA 中的高级使用示例

与在前面示例中通过提供工厂类名来创建隐式工厂实例的方法不同，您可以预先配置自己的工厂实例，并完全访问由工厂生成的 SelectriData 类使用的所有参数。

$data = SelectriContaoTableDataFactory::create();

// use the tl_page table for the tree structure
$data->setTreeTable('tl_page');

// show all nodes
$data->getConfig()->setTreeMode('all');

// search the title and pageTitle column
$data->getConfig()->setTreeSearchColumns(array('title', 'pageTitle'));

// only show nodes matching the condition
$data->getConfig()->setTreeConditionExpr('type = \'regular\' AND tstamp > 0');

// only let the user select nodes matching the condition
$data->getConfig()->setSelectableExpr('hide <> \'1\'');

// for more parameters see the factory class and the underlaying config class

$GLOBALS['TL_DCA']['tl_mydca']['fields']['mySelectriField'] = array(
	...
	'inputType' => 'selectri',
	...
	'eval' => array(
		'min'			=> 0,
		'max'			=> 1,
		'searchLimit'	=> 20,
		'tl_class'		=> 'clr',
		'class'			=> 'checkbox',
		
		// assign your preconfigured factory instance to the widgets configuration
		'data'			=> $data,
	),
	...
);