backboneit/contao-selectri

A selection widget for large structured option sets.

backboneit_selectri

A selection widget for large structured option sets., _(*1)

Usage in DCA

Input type token: selectri, _(*2)

eval Parameters

Value retrieval, _(*3)

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., _(*4)

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., _(*5)

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:, _(*6)

• findInSet - boolean - defaults to false, _(*7)

  • get: Returns a comma-separated list of the selected options' keys. This behavior takes precedence over the canonical setting., _(*8)

  • 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., _(*9)

• canonical - boolean - defaults to false, _(*10)

  • get: Returns the canonical form of the selection or, if max is set to 1, only the selected option's data array., _(*11)

  • set: A normalization to the canonical form is done., _(*12)

Basic widget configuration, _(*13)

• min - integer, non-negative - defaults to 0, _(*14)

  How many nodes must be selected at least., _(*15)

  If the max parameter is less than the configured minimum, the min parameter will be considered equal to the configured maximum., _(*16)

• max - integer, positive - defaults to 1, _(*17)

  How many nodes can be selected at most., _(*18)

• mandatory - boolean - optional - deprecated: the min parameter should be used, _(*19)

  If given and true, the min parameter will be set to 1, if it is not > 0 already. If given and false, the min parameter will be set to 0., _(*20)

• multiple - boolean - optional - deprecated: the max parameter should be used, _(*21)

  If given and true, the max parameter will be set to PHP_INT_MAX, if it is not > 1 already. If given and false, the max parameter will be set to 1., _(*22)

• searchLimit - integer, positive - defaults to 20, _(*23)

  The max nodes retrieved from searches., _(*24)

• sort - string, one of list, preorder, tree - defaults to list, _(*25)

  The structure implied on the made selection, _(*26)

  • list: the selection is a list (order matters), the selection is sortable
  • preorder not implemented: the selection is a set (order does not matter), the selection is not sortable and preordered
  • tree not implemented: the selection is a tree, the selection can be arranged with tree properties

• height - string - defaults to auto, _(*27)

  The CSS value and unit of the CSS height property of the selection tree., _(*28)

• tl_class - string - optional, _(*29)

  Only used in Backend., _(*30)

• class - string - optional, _(*31)

  Use 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., _(*32)

• data - string or an object implementing SelectriDataFactory - defaults to the string SelectriContaoTableDataFactory, _(*33)

  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 a SelectriData, as all data implementation specific features and options can be properly configured through their factories., _(*34)

  If a string is given, it must name a class implementing SelectriDataFactory. When creating the widget, a new factory instance is created and its setParameters method is called with the attributes of the widget (the widget's attributes contains all settings from the DCA's eval array)., _(*35)

Factory specific configuration (used by setParameters method of the SelectriDataFactory class given in the data parameter), _(*36)

• treeTable - string - optional, _(*37)

  The name of the table to fetch tree nodes from., _(*38)

  The parameter is used by SelectriContaoTableDataFactory::setParameters method and preconfigures the data according to common Contao standards like primary key column id and parent key column pid., _(*39)

• mode - string - defaults to all, _(*40)

  The parameter is used by SelectriTableDataFactory::setParameters method., _(*41)

  • all: all nodes are selectable
  • leaf: only leaf nodes are selectable
  • inner: 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., _(*42)

$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,
    ),
    ...
);