hofff / contao-selectri
A selection widget for large structured option sets.
Installs: 5 656
Dependents: 4
Suggesters: 0
Security: 0
Stars: 7
Watchers: 4
Forks: 4
Open Issues: 1
Type:contao-module
Requires
- php: ^5.6 || ^7.0
- contao-community-alliance/composer-plugin: ^2.0 || ^3.0
- contao/core-bundle: ^3.5 || ^4.3
Replaces
- backboneit/contao-selectri: 5.0.0-rc1
- contao-legacy/backboneit_selectri: 5.0.0-rc1
This package is auto-updated.
Last update: 2024-09-29 03:47:00 UTC
README
A selection widget for large structured option sets.
Usage in DCA
Input type token: selectri
eval Parameters
Value retrieval
The widgets canonical representation of selection values are arrays that map
selected nodes' keys to arrays containing the selected nodes' key at the array
key _key
as well as additional data associated with this selected node.
If you work with the widget directly, it is strongly recommended that you use the getValue/setValue methods, which will always return values in this canonical representation form.
If you however use this widget in DCAs, it is desired that the widget's value
property (which is used by the DCA) is converted to - on retrieval - or
converted from - on set - a specific format. To avoid the registration of
load/save callbacks, the value
property maintains an array of selected
options' keys or, if max
is set to 1
, a single selected option's key. For
commonly used conversions there exist the following eval properties to further
modify the value
's property content:
-
findInSet
- boolean - defaults tofalse
-
get: Returns a comma-separated list of the selected options' keys. This behavior takes precedence over the
canonical
setting. -
set: Strings are handled as comma-separated lists of selected options' keys and gets split at
,
. A normalization to the canonical form is done after.
-
-
canonical
- boolean - defaults tofalse
-
get: Returns the canonical form of the selection or, if
max
is set to1
, only the selected option's data array. -
set: A normalization to the canonical form is done.
-
Basic widget configuration
-
min
- integer, non-negative - defaults to0
How many nodes must be selected at least.
If the
max
parameter is less than the configured minimum, themin
parameter will be considered equal to the configured maximum. -
max
- integer, positive - defaults to1
How many nodes can be selected at most.
-
mandatory
- boolean - optional - deprecated: themin
parameter should be usedIf given and
true
, themin
parameter will be set to1
, if it is not> 0
already. If given andfalse
, themin
parameter will be set to0
. -
multiple
- boolean - optional - deprecated: themax
parameter should be usedIf given and
true
, themax
parameter will be set toPHP_INT_MAX
, if it is not> 1
already. If given andfalse
, themax
parameter will be set to1
. -
searchLimit
- integer, positive - defaults to20
The max nodes retrieved from searches.
-
sort
- string, one oflist
,preorder
,tree
- defaults tolist
The structure implied on the made selection
list
: the selection is a list (order matters), the selection is sortablepreorder
not implemented: the selection is a set (order does not matter), the selection is not sortable and preorderedtree
not implemented: the selection is a tree, the selection can be arranged with tree properties
-
height
- string - defaults toauto
The CSS value and unit of the CSS
height
property of the selection tree. -
tl_class
- string - optionalOnly used in Backend.
-
class
- string - optionalUse this to apply your custom CSS savely. You can use "radio" or "checkbox" to replace the Contao-style select (+) and deselect (x) icons with Windows legacy input-like icon images.
-
data
- string or an object implementingSelectriDataFactory
- defaults to the stringSelectriContaoTableDataFactory
If a factory object is given, these factory will be used to generate a data instance for created widgets. The
setParameters
method is not called. This is the recommended way to provide aSelectriData
, as all data implementation specific features and options can be properly configured through their factories.If a string is given, it must name a class implementing
SelectriDataFactory
. When creating the widget, a new factory instance is created and itssetParameters
method is called with the attributes of the widget (the widget's attributes contains all settings from the DCA'seval
array).
Factory specific configuration (used by setParameters
method of the
SelectriDataFactory
class given in the data
parameter)
-
treeTable
- string - optionalThe name of the table to fetch tree nodes from.
The parameter is used by
SelectriContaoTableDataFactory::setParameters
method and preconfigures the data according to common Contao standards like primary key columnid
and parent key columnpid
. -
mode
- string - defaults toall
The parameter is used by
SelectriTableDataFactory::setParameters
method.all
: all nodes are selectableleaf
: only leaf nodes are selectableinner
: only inner nodes are selectable
Simple example for usage in 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" ), ... );
Advanced example for usage in DCA
Instead of using a implicit created factory instance by providing a factory
class name in the previous example, you can preconfigure your own factory
instance and have full access to all parameters used by the SelectriData
-class
produced by the factory.
$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, ), ... );