Skip to content

Migrating to Version 3

Jump to bottom Edit New page
Steve James edited this page Mar 12, 2018 · 53 revisions

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 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

  • multiple - The widget now directly references whether the multiple option is set on the underlying native select.
  • minWidth - This option has been replaced by the buttonWidth option, since essentially minWidth was setting the button width in the past.
  • checkAllText - The linkInfo option is now used for configuring all link text and icons.
  • uncheckAllText - 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.
  • 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.

2. Renamed Options

  • height- Renamed as menuHeight.
  • show - Renamed as openEffect.
  • hide - Renamed as closeEffect.

3. New Option Usage

  • header - In addition to false or string value, an array of keywords (e.g., 'checkAll') can now be specified for the header option to specify what links to show in the header and in what order.
  • buttonWidth, menuWidth, & menuHeight - These can now take a variety of units (e.g. '2in') 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.
  • 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

  • resizableMenu - This option makes the menu height resizable if the resizable widget is loaded.
  • zIndex - This option allows you to override the widget's automatic determination of best z-index for the menu, if needed.
  • 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 i18n code details for how to do this.

  • maxSelected - This option allows you specify that a maximum number of options can be selected.
  • htmlText - This option allows you to specify in which parts of the widget ('button' &/or 'options') that the text be treated as html.
  • wrapText - This option allows you to specify in which parts of the widget ('button', 'header', &/or 'options') that the text should be wrapped.
  • 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).
  • addInputNames - This option allows you to control whether the widget creates input names for each checkbox input.
  • groupsSelectable - This option allows you to control whether the option groups can selected at once by clicking on the option header.
  • 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.

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.
  • 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.
Add a custom footer
Add a custom sidebar
Clone this wiki locally