Migrating to Version 3

Version 3 of the multiselect widget is intended to keep the best parts of the past versions while making improvements and adding useful features.

Key things to keep in mind:

1. The CSS files now land in their own sub-folder. If you have been using prior versions of the widget, you will very likely need to change your file paths for the CSS files.

2. The names and usage of a number of options have changed. In most cases, the name changes were intended to make it clearer what the options were actually for. Option usage was changed where it made sense to combine option values or to keep the number of options from endlessly increasing.

3. Additionally, there have been a number of new options added.

4. To support the new features and functionality, a number of new widget methods and events have also been added.

The purpose of this wiki page is not to comprehensively describe each option in Version 3. Instead, we are just pointing out where there are changes. The other wikis that describe the options will be updated to reflect the new options and usage.

1. Eliminated Options

• checkAllText - The linkInfo option is now used for configuring all link text and icons.
• closeIcon - The linkInfo option is now used for configuring all link text and icons.
• multiple - The widget now directly references whether the multiple option is set on the underlying native select.
• showCheckAll - Specifying the display and order of header links is now done with the header option.
• showUncheckAll - Specifying the display and order of header links is now done with the header option.
• uncheckAllText - The linkInfo option is now used for configuring all link text and icons.

2. Renamed Options

• height- Renamed as menuHeight.
• hide - Renamed as closeEffect.
• minWidth - Renamed as buttonWidth.
  (Essentially minWidth was setting the button width in the past.)
• show - Renamed as openEffect.

3. New Option Usage

• buttonWidth, menuWidth, & menuHeight - These can now take a variety of units (e.g. '2in', '14pt', etc.) specified as part of the dimension. Additionally, the width dimensions can be specified as minimum values w/ the '>=' syntax. Lastly, each can take 'auto' as their value, and 'size' can be specified for the height dimension to make the widget reference the size attribute of the underlying native select.
• header - In addition to false or string value, an array of link identifiers (e.g., ['uncheckAll','checkAll']) can now be specified for the header option to specify what links to show in the header and in what order.
• position - When using this option, you do not have to specify an entire object, as the position properties you do specify are merged internally with the default position object via an $.extend().

Note: The default position object is
{'my': 'left top', 'at': 'left bottom', 'of': $button}.

4. New Options

• addInputNames - This option allows you to control whether the widget creates input names for each checkbox input. If you are serializing the underlying select element for submittal to the server via AJAX, then it may be unnecessary for the widget to also create input names.
• groupsCollapsable - This option allows you to control whether the option groups can collapsed by clicking on the collapse button that is displayed for each option header.
• groupsSelectable - This option allows you to control whether the option groups can selected/de-selected at once by clicking on the option header.
• htmlText - This option allows you to provide an array of keywords to specify in which parts of the widget ('button' &/or 'options') that the text be treated as html.
• linkInfo - This option allows you to provide a configuration object to specify alternative text, icons, and titles for the links used in the header (and button). Refer to the linkDefaults object in the code for proper object structure.

Note: As an $.extend() is used to merge anything specified via linkInfo with the defaults in the linkDefaults object, you do not need to specify all link details, just the ones you want to change from the defaults. Additionally, you can override the link details for all instances of the widget--refer to the Customization wiki page for how to do this.

• listbox - This option allows you to specify that the widget should not create a button and should be inserted in the html immediately after the native select (not a pop-up).
• maxSelected - This option allows you specify that a maximum number of options can be selected.
• resizableMenu - This option makes the menu height resizable if the resizable widget is loaded.
• wrapText - This option allows you to provide an array of keywords to specify in which parts of the widget ('button', 'header', &/or 'options') that the text should be wrapped.
• zIndex - This option allows you to override the widget's automatic determination of best z-index for the menu, if needed.

5. New Filter Options

• filterRule - This option allows you to specify alternative filter rules from the default "contains" filter rule.
• searchGroups - This option makes the filter also search option headings.

6. New Widget Methods

• buttonMessage - Displays a message in the button for one second.
• collapseAll - Collapse all option groups or just the one specified by optional parameteter groupID.
• expandAll - Expand all option groups or just the one specified by optional parameter groupID.
• flipAll - Invert (flip) all options checked state or just the option group specified by optional parameter groupID.
• getCollapsed - Returns an array of the currently collapsed option groups.
• getNamespaceID - Returns the namespace ID of the current widget instance.
• resync - Re-synchronizes the menu options checked state with the selected state of the native select's options without having to rebuild the menu via refresh.
• value - Sets or returns the value of the underlying select element. If setting, the widget's menu options are re-synchonized with the underlying select via the resync() method.