Multiple Choice Combobox (<b:selectMultiMenu>)

This is a special combobox that allows you to select an arbitrary number of items without sacrificing a lot of screen estate.

Both the values and the labels of the items are expected to be strings. If the user selects more than one item, the combobox displays every selected label separated by commas. Likewise, the value of the combobox is a comma-separated list of the item values. You can see both effects in the live demo below.

Kudos

This widget is based on the Bootstrap Multiselect widget written by David Stutz.

License

The original widget is available both under the Apache V2 license and the BSD 3-Clause License. Please note that this is a different license than BootsFaces itself, which has been put under a GPL V3 license (or - at your option - any later version).

Basic usage

The Java bean receives a comma-separated list of the selected values. Note that "no selection" results in an empty string. The attribute of the Java bean may contain a null value when the page is rendered, but requests never set null values.

AJAX since 1.0.2

<b:selectMultiMenu /> supports many AJAX callbacks. However, many standard AJAX callbacks are not supported. For instance, there's no onblur event. As an alternative, this example uses ondropdownhide:

Events supported by AJAX:

Options

radiobuttons
Converts the multiple-choice widget into a single-choice combobox.
maxHeight
Maximum height of the options panel.
nonSelectedText
Text which is displayed if no option has been selected.
nSelectedText, numberDisplayed
Maximum number of options displayed in the button. Text which is displayed if more than numberDisplayed options have been selected.
allSelectedText
Text which is displayed if every option has been selected.
includeSelectAllOption
If true, you can select every option with a single click.
selectAllText
The text displayed for the select all option.
enableFiltering, filterPlaceholder
Set to true or false to enable or disable the filter. A filter input will be added to dynamically filter all options. The placeholder used for the filter input.
enableFiltering, enableCaseInsensitiveFiltering, filterPlaceholder
Set to true or false to enable or disable the filter. A filter input will be added to dynamically filter all options. The placeholder used for the filter input.
dropRight
Moves the drop-down-area from the left hand side to the right hand side.
disableIfEmpty
If true, the button is disabled if no options are given.
onchange
Client side callback to execute when input element loses focus and its value has been modified since gaining focus.
ondropdownshow
Client side callback called when the drop-down area is shown.
ondropdownhide
Client side callback called when the drop-down area is hidden.
buttonClass
The CSS class of the button.
styleClass
Style class of the input element. Is translated to the buttonContainer attribute.
buttonWidth
The width of the multiselect button may be fixed using this option.

Append and prepend

You can use the prepend facet to put an element seamlessly in front of the multiple choice combobox. However, the append facet doesn't work yet. It is displayed, but not seamlessly next to the combobox. In any case, both facets don't match the look and feel of the multi-selectbox exactly, so you need to apply some CSS code to improve it.

@.com

Objects and converters

<b:selectMultiMenu> only works with strings. The value must not be any other data type. So don't bother with converters - we officially don't support them.

Arrays and HashMaps

The list of items can be defined as an <f:selectItems /> tag. BootsFaces uses a modified version of the algorithm PrimeFaces 5.1 uses to implement <f:selectItems />. As a result, you can use <b:selectMultiMenu> almost the same way as <prime:selectOneMenu>.

)

Labels as captions above the combobox

By default, BootsFaces displays the label above the input field. However, in the case of the multiple choice combobox, we didn't implement this feature yet.


Responsive design since 0.9.0

You can use all the attributes controlling the responsive behaviour of <b:column /> also with <b:icon />:

Visibility depending on screen size since 0.8.6/0.9.0

You can play also with col-*-*, visible and hidden attribute, as any bootstrap elements. For example:


Visible on >= md:
Visible on <= sm:
Visible on sm...lg:
Visible on xs and md:
Col-md-6, offset 2:

Tooltips

<b:selectMultiMenu /> supports tooltips:




Attribute Default value Description
accesskey (none) Access key to transfer focus to the input element.
ajax false Whether the Button submits the form with AJAX.
all-selected-text
allSelectedText (alternative writing)
(none) Text which is displayed if every option has been selected.
alt (none) Alternate textual description of the input element.
binding (none) An EL expression referring to a server side UIComponent instance in a backing bean.
button-container
buttonContainer (alternative writing)
(none) HTML snippet of the container holding both the button as well as the dropdown. Default: <div class='btn-group' style='display:block' />. Note that the original definition of the widget doesn't use the style definition. We've added it to fix a rendering bug.
button-width
buttonWidth (alternative writing)
0 The width of the multiselect button may be fixed using this option.
buttonClass (none) The CSS class of the button.
col-lg
colLg (alternative writing)
-1 Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-md
colMd (alternative writing)
-1 Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-sm
colSm (alternative writing)
-1 Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
col-xs
colXs (alternative writing)
-1 Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
dir (none) Direction indication for text that does not inherit directionality. Legal values: ltr (Default. Left-to-right text direction), rtl (Right-to-left text direction) and auto (let the browser figure out the direction of your alphabet, based on the page content).
disable-if-empty
disableIfEmpty (alternative writing)
false If true, the button is disabled if no options are given.
disabled false Disables the input element, default is false.
display block If you use the "visible" attribute, the value of this attribute is added. Legal values: block, inline, inline-block. Default: block.
dropRight false Moves the drop-down-area from the left hand side to the right hand side.
enable-case-insensitive-filtering
enableCaseInsensitiveFiltering (alternative writing)
false If set to true, the filter is case-insensitive.
enable-filtering
enableFiltering (alternative writing)
false Set to true or false to enable or disable the filter. A filter input will be added to dynamically filter all options.
field-size
fieldSize (alternative writing)
(none) The size of the input.Possible values are xs (extra small), sm (small), md (medium) and lg (large) .
filter-placeholder
filterPlaceholder (alternative writing)
(none) The placeholder used for the filter input.
hidden (none) This column is hidden on a certain screen size and below. Legal values: lg, md, sm, xs.
id (none) Unique identifier of the component in a namingContainer.
immediate false Flag indicating that, if this component is activated by the user, notifications should be delivered to interested listeners and actions immediately (that is, during Apply Request Values phase) rather than waiting until Invoke Application phase. Default is false.
include-select-all-option
includeSelectAllOption (alternative writing)
false If true, you can select every option with a single click.
inline false Inline forms are more compact and put the label to the left hand side of the input field instead of putting it above the input field. Inline applies only to screens that are at least 768 pixels wide.
label (none) The Label of the field .
label-col-lg
labelColLg (alternative writing)
-1 Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-col-md
labelColMd (alternative writing)
-1 Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-col-sm
labelColSm (alternative writing)
-1 Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-col-xs
labelColXs (alternative writing)
-1 Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-large-screen
labelLargeScreen (alternative writing)
-1 Alternative spelling to col-lg. Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-medium-screen
labelMediumScreen (alternative writing)
-1 Alternative spelling to col-md. Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-small-screen
labelSmallScreen (alternative writing)
-1 Alternative spelling to col-sm. Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
label-style
labelStyle (alternative writing)
(none) The CSS inline style of the label.
label-style-class
labelStyleClass (alternative writing)
(none) The CSS class of the label.
label-tiny-screen
labelTinyScreen (alternative writing)
-1 Alternative spelling to col-xs. Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
lang (none) Code describing the language used in the generated markup for this component.
large-screen
largeScreen (alternative writing)
-1 Alternative spelling to col-lg. Integer value to specify how many columns to span on large screens (≥1200 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
max-height
maxHeight (alternative writing)
0 Maximum height of the options panel.
medium-screen
mediumScreen (alternative writing)
-1 Alternative spelling to col-md. Integer value to specify how many columns to span on medium screens (≥992 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
n-selected-text
nSelectedText (alternative writing)
(none) Text which is displayed if more than numberDisplayed options have been selected.
non-selected-text
nonSelectedText (alternative writing)
(none) Text which is displayed if no option has been selected.
number-displayed
numberDisplayed (alternative writing)
0 Maximum number of options displayed in the button.
offset (none) Integer value to specify how many columns to offset.
offset-lg
offsetLg (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-md
offsetMd (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-sm
offsetSm (alternative writing)
(none) Integer value to specify how many columns to offset.
offset-xs
offsetXs (alternative writing)
(none) Integer value to specify how many columns to offset.
onchange (none) AJAX event: A function which is triggered on the change event of the options. Note that the event is not triggered when selecting or deselecting options using the select and deselect methods provided by the plugin.
onclick (none) The onclick attribute.
oncomplete (none) JavaScript to be executed when ajax completes.
ondeselectall (none) AJAX event: This function is triggered when the select all option is used to deselect all options. Note that this can also be triggered manually using the .multiselect('deselectAll') method.
ondropdownhidden (none) AJAX event: A callback called after the dropdown has been closed.
ondropdownhide (none) AJAX event: A callback called when the dropdown is closed.
ondropdownshow (none) AJAX event: A callback called when the dropdown is shown.
ondropdownshown (none) AJAX event: A callback called after the dropdown has been shown.
onerror (none) JavaScript to be executed when ajax results on an error (including both network errors and Java exceptions).
oninitialized (none) AJAX event: A function which is triggered when the multiselect is finished initializing.
onselectall (none) AJAX event: This function is triggered when the select all option is used to select all options. Note that this can also be triggered manually using the .multiselect('selectAll') method.
onsuccess (none) JavaScript to be executed when ajax completes with success (i.e. there's neither a network error nor a Java exception).
process (none) Comma or space separated list of ids or search expressions denoting which values are to be sent to the server.
radiobuttons false Set to true to display radiobuttons instead of checkboxes. Of course, in this case you can only select one option, so the widget's name is sort of a misnomer.
readonly false Flag indicating that this input element will prevent changes by the user.
render-label
renderLabel (alternative writing)
net.bootsfaces.component.ComponentUtils.isRenderLabelDefault() Allows you to suppress automatic rendering of labels. Used internally by AngularFaces, too.
rendered false Boolean value to specify the rendering of the component, when set to false the component will not be rendered.
required false Boolean value Require input in the component when the form is submitted.
required-message
requiredMessage (alternative writing)
(none) Message to show if the user did not specify a value and the attribute required is set to true.
select-all-text
selectAllText (alternative writing)
(none) The text displayed for the select all option.
size 0 Number of characters used to determine the width of the input element.
small-screen
smallScreen (alternative writing)
-1 Alternative spelling to col-sm. Integer value to specify how many columns to span on small screens (≥768p pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
span (none) Integer value to specify how many columns to span on medium screens (≥992 pixels). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
style (none) Inline style of the input element.
style-class
styleClass (alternative writing)
(none) Style class of the input element. Is translated to the buttonContainer attribute.
tabindex (none) Position of this element in the tabbing order for the current document. This value must be an integer between 0 and 32767.
tiny-screen
tinyScreen (alternative writing)
-1 Alternative spelling to col-xs. Integer value to specify how many columns to span on tiny screens (≤ 767 pixels wide). The number may optionally be followed by "column" or "columns". Alternative legal values: half, one-third, two-thirds, one-fourth, three-fourths.
title (none) Advisory tooltip information.
tooltip (none) The text of the tooltip.
tooltip-container
tooltipContainer (alternative writing)
body Where is the tooltip div generated? That's primarily a technical value that can be used to fix rendering errors in special cases. Also see data-container in the documentation of Bootstrap. The default value is body.
tooltip-delay
tooltipDelay (alternative writing)
0 The tooltip is shown and hidden with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-delay-hide
tooltipDelayHide (alternative writing)
0 The tooltip is hidden with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-delay-show
tooltipDelayShow (alternative writing)
0 The tooltip is shown with a delay. This value is the delay in milliseconds. Defaults to 0 (no delay).
tooltip-position
tooltipPosition (alternative writing)
(none) Where is the tooltip to be displayed? Possible values: "top", "bottom", "right", "left", "auto", "auto top", "auto bottom", "auto right" and "auto left". Default to "bottom".
update (none) Component(s) to be updated with ajax.
value (none) Value.
visible (none) This column is shown on a certain screen size and above. Legal values: lg, md, sm, xs.
  • The combobox is a select tag bearing the CSS-class form-control.
  • If the attribute required is true, the pseudo CSS class bf-required is added. Thus you can define your custom style for required fields.
  • If there's a FacesMessage, the input field is bears one of the pseudo CSS classes bf-info, bf-warning, bf-error or bf-fatal. If there's no message, the input field bears the pseudo CSS class bf-no-message and has-success. The latter colors the label green by default.
  • If there's a label, it bears the CSS class required, if it's a mandatory field. This class adds an asterisk to the label text. You can override the CSS class to remove the asterisk or to replace it by something else.
  • If there's a label, it bears the CSS classes bf-info, bf-warning, bf-error or bf-fatal, depending on which severity the error message the input field has. The latter two classes color the label red.
    If there's no message, the input field bears the pseudo CSS class bf-no-message and has-success. The latter colors the label green by default.