echmultiselect

This is a simple Wrapper Widget for the jQuery UI MultiSelect Widget by Eric Hynds.
Details about the widget can be found here.
A Demo of the JQuery widget can be found here.

Requirements ¶

Tested with Yii 1.1.8.

Unpack the widget ¶

Extract the contents of the zip file directly into the protected/extensions/widgets/ folder of your Yii application.

Use the widget ¶

1. Basic Use with model and dropDownAttribute ¶

Now you can use the widget in your view file, for example like this:

$data= CHtml::listData(Color::model()->findAll(), 'ID', 'Name');
$this->widget('ext.widgets.EchMultiselect', array(
    'model' => $model,
    'dropDownAttribute' => 'color',     
    'data' => $data,
    'dropDownHtmlOptions'=> array(
        'style'=>'width:378px;',
    ),
));

This Yii widget creates a 'drop down list' with the given data and applies the JQuery widget to it, which turns the ordinary HTML select control into an elegant MultiSelect list of checkboxes with themeroller support.

To avoid confusion: I refer to the initial select element (that is subsequently hidden) as the 'drop down list'; and to the eventual input element created by the JQuery Widget as the 'MultiSelect list'.

The provided 'dropDownHtmlOptions' will be adopted by the MultiSelect list. If you for example provide a style for the drop down list, it will also applied to the resulting MiltiSelect list.

The drop down list will be hidden directly after it is created: I placed a Javascript code to hide the element directly after it, to prevent it from being displayed while the page is loading, only to be hidden after the page has been loaded (as suggested here). I truly dislike that appearing/disappearing on page load, so I didn'd wait for the MultiSelect widget to hide the drop down list.

2. Basic Use with name and value ¶

$colors = array('red','yellow','orange','black','green','blue');
$this->widget('ext.widgets.EchMultiselect', array(
    'name'=>'colors',
    'data'=>$colors,
    'value'=>array(0,3),
    'dropDownHtmlOptions'=> array(
        'class'=>'span-10',
        'id'=>'colors',
    )
));

Here, name is the name of the drop down list. This must be set if model and dropDownAttribute are not set.
value contains the selected input value(s). In this case, 'red' and 'yellow' will be selected by default. value is used only if model is not set.

If model and dropDownAttribute are specified, they are used to generate the name and id of the drop down list. Note that if name is specified in addition, it overrides the automatically generated name. Similarly, if id is specified in the dropDownHtmlOptions, it overrides the generated id.

3. Overriding default options and filterOptions ¶

You can provide optional parameters for the JQuery widget, if you want to change their default settings. Here's an example:

$data= CHtml::listData(Color::model()->findAll(), 'ID', 'Name');
$this->widget('ext.widgets.EchMultiselect', array(
    'model' => $model,
    'dropDownAttribute' => 'color',     
    'data' => $data,    
    'dropDownHtmlOptions'=> array(
        'style'=>'width:378px;',
    ),
    'options' => array( 
        'header'=> Yii::t('application','Choose an Option!'),
        'minWidth'=>350,
        'position'=>array('my'=>'left bottom', 'at'=>'left top'),
        'filter'=>true,
    ),
    'filterOptions'=> array(
        'width'=>150,
    ),
));

Now the default “check all”, “uncheck all”, and “close” links in the header will be replaced with the specified text 'Choose an Option!, the widget will have a minimum width of 350px (instead of the default 225px), and the filter plugin will be applied.

Details about the available 'options' and 'filterOptions' for the jQuery UI MultiSelect Widget can be found on the Project page. Here's a list of the options and their default values for quick reference:

// 'options':
'header'=> true,
'height'=>175,
'minWidth'=>225,
'position'=>'',
'checkAllText' => Yii::t('application','Check all'),
'uncheckAllText' => Yii::t('application','Uncheck all'),
'selectedText' =>Yii::t('application','# selected'),
'selectedList'=>false,
'show'=>'',
'hide'=>'',
'autoOpen'=>false,
'noneSelectedText'=>'-- ' . Yii::t('application','Select Options') . ' --',
'multiple'=>true,
'classes'=>'',
'filter'=>false,
// 'filterOptions':
'label' => Yii::t('application','Filter:'),
'width'=>100,
'placeholder'=>Yii::t('application','Enter keywords'),
'autoReset'=>false,

The filter plugin is disabled by default. To enable it, you have to set the filter attribute to true. The filterOptions will have no effect, if filter is set to false, i.e. the filter plugin is disabled.

Note that the default options are already translated with Yii::t() where necessary.

For details about the position option see the jQuery page for the Position utility. The default position of the Multiselect list array('my'=>'left top', 'at'=>'left bottom').

4. import widgets in config file to simplify calls ¶

As an alternative, you can import the path of your widgets in your config file
protected/config/main.php:

'import'=>array(
    ...
    'ext.widgets.*',
    ...
),

Note that ext is short for application.extensions. Now you can call this widget (and any other widgets you may have placed under extensions/widgets/ ) with only its name, without specifying its path, i.e. like this:

$this->widget('EchMultiselect',...);

Changes ¶

• Mar 12, 2012 (v1.2)
  • Zipped the Widget-files directly, without putting them into an additional EchMultiSelect directory. That is: only directory structure changed. No changes in the code! (Reason of the change: The contents of the zip file are often extracted directly into the extensions directory, which resulted in the need to call the widget with $this->widget('ext.widgets.EchMultiselect.EchMultiselect', array(...);)
• Feb 06, 2012 (v1.1)
  • Added the ability to pass options to the MultiSelect Filter Widget via parameter 'filterOptions' (thanks to sucotronic for pointing this out in the forum).
  • Made sure 'multiple' attribute of drop down list is set to 'true', even if not explicitly set in 'dropDownHtmlOptions' (only if 'multiple'=>true in 'options' of course).
  • Fixed a bug regarding the 'name' parameter

Note for versions v1.1 and v1.0 ¶

• If you extract these versions directly into the protected/extensions/widgets/ directory, the widget file EchMultiSelect.php will be located within the folder 'EchMultiSelect' (take a look at the file structure). So the path to this widget-file will be protected/extensions/widgets/EchMultiselect/EchMultiSelect.php. Therefore you will need to call the widget with:

$this->widget('ext.widgets.EchMultiselect.EchMultiselect', array(...));

• If you:
  1. Extract the zip file to some place, which results in the folder EchMultiSelect.
  2. Copy the files that are within this new folder EchMultiSelect into the protected/extensions/widgets/ directory of your application, you can use the widget as intended with:

$this->widget('ext.widgets.EchMultiselect', array(...));

Resources ¶

• Project page of JQuery widget: http://www.erichynds.com/jquery/jquery-ui-multiselect-widget/
• Demo of JQuery widget : http://www.erichynds.com/examples/jquery-ui-multiselect-widget/demos/#filter
• JQuery widget on github: https://github.com/ehynds/jquery-ui-multiselect-widget
• Extension page in the forums: http://www.yiiframework.com/forum/index.php?/topic/28524-echmultiselect-widget/