softark/yii2-dual-listbox

Dual Listbox Widget for Yii 2

yii2-dual-listbox

Dual Listboxt for Yii framework 2.0., _(*1)

Description

softark\duallistbox\DualListbox widget is a Yii 2 wrapper for Bootstrap Dual Listbox., _(*2)

It works with bootstrap 3, 4, or 5, _(*3)

Requirements

• Yii Version 2.0.0 or later
• yii2-bootstrap, yii2-bootstrap4 or yii2-bootstrap5
• istvan-ujjmeszaros/bootstrap-duallistbox v.3.0.x or v.4.0.x

Usage

1. Add softark/yii2-dual-listbox and istvan-ujjmeszaros/bootstrap-duallistbox in your project's composer.json, and let Composer configure your project., _(*4)

   • You have to use a different version of istvan-ujjmeszaros/bootstrap-duallistbox depending on the bootstrap version.
   • For bootstrap 3, use ~3.0.0 :

   "require": {
       "php": ">=7.0.0",
       "yiisoft/yii2": "*",
       "yiisoft/yii2-bootstrap": "*",
       "istvan-ujjmeszaros/bootstrap-duallistbox": "~3.0.0",
       "softark/yii2-dual-listbox": "dev-master"
   },
   

   • For bootstrap 4 and 5, use ~4.0.0:

   "require": {
       "php": ">=7.0.0",
       "yiisoft/yii2": "*",
       "yiisoft/yii2-bootstrap4": "*", // OR
       "yiisoft/yii2-bootstrap5": "*",
       "istvan-ujjmeszaros/bootstrap-duallistbox": "~4.0.0",
       "softark/yii2-dual-listbox": "dev-master"
   },
   

2. Use softark\duallistbox\DualListbox::widget() in place of yii\helpers\Html::listBox(), yii\helpers\Html::activeListBox(), or yii\widgets\ActiveField::listBox() in your view., _(*5)

   1. Replacing Html::listBox() using name and selection, _(*6)

      use softark\duallistbox\DualListbox;
      ...
      <?php
         $options = [
             'multiple' => true,
             'size' => 20,
         ];
         // echo Html::listBox($name, $selection, $items, $options);
         echo DualListbox::widget([
             'name' => $name,
             'selection' => $selection,
             'items' => $items,
             'options' => $options,
             'clientOptions' => [
                 'moveOnSelect' => false,
                 'selectedListLabel' => 'Selected Items',
                 'nonSelectedListLabel' => 'Available Items',
             ],
         ]);
      ?>
      

   2. Replacing Html::activeListBox() using model and attribute, _(*7)

      use softark\duallistbox\DualListbox;
      ...
      <?php
         $options = [
             'multiple' => true,
             'size' => 20,
         ];
         // echo Html::activeListBox($model, $attribute, $items, $options);
         echo DualListbox::widget([
             'model' => $model,
             'attribute' => $attribute,
             'items' => $items,
             'options' => $options,
             'clientOptions' => [
                 'moveOnSelect' => false,
                 'selectedListLabel' => 'Selected Items',
                 'nonSelectedListLabel' => 'Available Items',
             ],
         ]);
      ?>
      

   3. Replacing ActiveField::listBox() using model and attribute, _(*8)

      use softark\duallistbox\DualListbox;
      ...
      <?php
         $options = [
             'multiple' => true,
             'size' => 20,
         ];
         // echo $form->field($model, $attribute)->listBox($items, $options);
         echo $form->field($model, $attribute)->widget(DualListbox::className(),[
             'items' => $items,
             'options' => $options,
             'clientOptions' => [
                 'moveOnSelect' => false,
                 'selectedListLabel' => 'Selected Items',
                 'nonSelectedListLabel' => 'Available Items',
             ],
         ]);
      ?>
      

3. Collect the user input in the server side, just as you do with a single Listbox with multiple selection. Note that the input value will be an array., _(*9)

   If you find difficulty in handling the user input, please read A Sample Code which demonstrates how to use a dual listbox to the data in array format., _(*10)

Properties of softark\duallistbox\DualListbox

1. name @var string, _(*11)

   The input name., _(*12)

2. selection @var array, _(*13)

   The selected values., _(*14)

3. model @var yii\base\Model, _(*15)

   The model object., _(*16)

4. attribute @var string, _(*17)

   The attribute name., _(*18)

5. items @var array, _(*19)

   The option data items. The array keys are option values, and the array values are the corresponding option labels., _(*20)

6. options @var array, _(*21)

   The tag options for the listbox in terms of name-value pairs., _(*22)

7. clientOptions @var array, _(*23)

   The options for the Bootstrap Dual Listbox in terms of name-value pairs. See Initialzation parameters object section of the official documentation of Bootstrap Dual Listbox for details., _(*24)

The first 6 properties correspond to the parameters used in Html::listBox(), Html::activeListBox() and ActiveField::listBox()., _(*25)

Note that you have to use either name-selection pair or model-attribute pair. The former is for replacing Html::listBox() and the latter is for Html::activeListBox() and ActiveField::listBox()., _(*26)

Notice

For some reason, Bootstrap Dual Listbox doesn't work in mobile device browsers, and so you can not use this widget for them., _(*27)

Consider using checkbox list instead., _(*28)

History

• Version 1.0.0 (2016-01-12)
  • Tested on Yii 2.0.6
• Version 1.0.1 (2020-09-18)
  • Supports both bootstrap3 and bootstrap4
• Version 1.0.2 (2022-09-08)
  • Supports also bootstrap5