Integrating with Dialogs

Implementing the Multiselect widget in dialogs is a common usage scenario. There are several considerations to keep in mind for best results.

If you are integrating the dialog into jQuery UI dialogs, then you need to check for whether height of the dialog and the placement of the widget button in the dialog leads to truncation of the widget's menu. This truncation is caused by the widget being appended to a container that has overflow: hidden set and has the same z-index as the widget's menu. The widget is preferentially appended to containers with the ui-front class (and overflow: hidden) set such as the jQuery UI dialog. While this certainly addresses the stacking order for multiple jQuery UI widgets shown on screen, it can also lead to menu truncation in the case of a short dialog and/or tall widget menu.

How To Fix: If you are seeing menu truncation, then you should first try explicitly setting the appendTo option to document.body. Alternatively, if you have a sufficiently tall dialog, you can try setting the within property for the position object to the jQuery object you set the dialog on so that the widget's menu is forced to be constrained in the interior scrolling portion of the dialog. (This latter approach presumes you are using the jQuery UI position feature.)
When appending to the body, you need to be aware that you may need to adjust the z-index of the menu so that it the menu is not obscured by the dialog itself. The widget attempts to make a determination for the best z-index, but in case it makes a bad guess, you can override it via the zIndex option.

If you are integrating the dialog into a jQuery UI modal dialog, you should be aware that, by design, modal dialogs attempt to block interaction or access to any HTML elements that are not descendants of the modal dialog itself. The multiselect widget now makes use of the jQuery UI _allowInteraction extension point for jQuery UI dialogs to ensure that the widget is "whitelisted" and can be interacted with.

Other dialogs. You may run into z-index and interaction issues with modal dialogs, particularly if you must append append to the document.body to prevent menu truncation. The zIndex option is available, which should help but different modal tools may present unique challenges for integration.

When setting the button width via the buttonWidth option, you should be aware that setting the width as a percentage (%) may not work correctly if you instantiate the widget in the dialog's create event handler as is typical. This is because the dialog's div container is hidden in the create event, and the widget needs a visible parent element to correctly determine the width of the button's parent for the percentage calculation.

How To Fix: You can instantiate the widget in the dialog's open event handler. Alternatively, you can address this by setting the button's width explicitly, setting the buttonWidth option to null to force the underlying native select's width to be used, or via setting it in the dialog's open event handler when the dialog is visible.

Similarly, when using the widget's listbox option, you should be aware that the widget's dimensions may not be set correctly if you instantiate the widget in the dialog's create event handler as is typical. This is because the dialog's div container is hidden in the create event, and the widget needs visible elements to correctly determine its width and height.

How To Fix: You can instantiate the widget in the dialog's open event handler. Alternatively, you can address this by setting the width and height in the dialog's open event handler when the dialog is visible. For example,

open: function() {
   $('select').multiselect('option','menuWidth', '200');
   $('select').multiselect('option','menuHeight', 'auto');
},

Provide feedback