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.
This widget is based on the Bootstrap Multiselect widget written by David Stutz.
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).
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.
<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:
By default, the multiple-choice select box doesn't respect the form-group
properties. In other words, it's smaller than the other input fields, which use all
available space in a <b:column />. You can fix this with a few lines
of CSS code:
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.
<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.
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>.
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.
You can use all the attributes controlling the responsive behaviour of <b:column />
also with <b:icon />:
You can play also with col-*-*, visible and hidden attribute, as any bootstrap elements. For example:
<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. |
| auto-update autoUpdate (alternative writing) |
false | Setting this flag updates the widget on every AJAX request. |
| 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. |
| delay | (none) | Delays the AJAX request. |
| 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. |
select tag bearing the CSS-class form-control.
required is true, the pseudo CSS class bf-required is added. Thus you can define your custom style for required fields.
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.
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.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.bf-no-message and has-success. The latter colors the label green by default.