The <b:commandButton />
tag extends the standard <h:commandButton />
with AJAX, partial processing features
and improved search expressions. Last not least, it adds the Bootstrap style.
The BootsFaces command button is used similarly to the PrimeFaces command button:
ajax="true"
.render
attribute of standard JSF, BootsFaces follows the
tradition coined by PrimeFaces, using the attribute update
to define which region of
the HTML page is to be updated.update
attributes supports the full range of BootsFaces search expressions,
such as @next
, @parent
and so on.
See the page on improved search expressions for more details.process
attribute allows you to influence partial processing. In the case
of the command button, the default value is @form
. You can use the process
attribute to reduce the number of input fields sent to the server.By default, command buttons are gray (depending on your theme). You can configure them by using a different look:
The <b:commandButton >
supports the full suite of JavaScript and AJAX events,
as described in the description of AJAX in BootsFaces. Basically, each of the
many JavaScript callback handlers (the on[event]
attributes) also supports AJAX.
At the time of writing (Sept 25, 2015), the list of supported events is blur, change, click, dblclick, focus, keydown, keypress,
keyup, mousedown, mousemove, mouseout, mouseover, mouseup and select.
Be careful with the actionListener
and the action
callback when using one of
the JavaScript event listeners to call AJAX. The actionListener
and the action
are always called, no matter which event originally triggered the AJAX call. As for the call order:
on[event]
is called first.
actionListener
is called second. It's a Java method that may or may not take the ActionEvent
as attribute.action
is called last. This is because it's the only Java method that may trigger a navigation to another page.
In order to trigger a navigation, this method may return a
String, which triggers a navigation to another page (unless it is null).
Note that navigations ignore the update
attribute, if the command button is declared as an AJAX button.
That's because an AJAX navigation usually replaces the entire page. Therefore, AJAX navigations are
always performed using update="@all"
The command button allows you to freely mix JavaScript calls and AJAX calls in the JavaScript
callback attributes. The demo below uses this feature to suppress AJAX calls on simple click or on double clicks if the corresponding
check box is set. It also calls Java method when the mouse point enters the command button (onmouseover
),
and when it leaves it again (onmouseout
):
To get familiar with BootsFaces AJAX, try the BootsFaces AJAX demo project.
If BlockUI is active, every AJAX request triggers a mouseOutEvent
. When the AJAX request has
been processed and the BlockUI overlay pane is hidden, a mouseOverEvent
is triggered. Keep this
in mind if you need to use the mouse events. We had to deactivate the BlockUI in order to make the demo above work.
Like Buttons, also CommandButtons can can have an icon adding the attribute
icon
(on the left or right, default is left).
You can control the icon position by specifying it in the attribute
iconAlign
.
The Icon attribute will add a Glyphicon icon (Bootstrap's default), but now you can also use a Font Awesome icon using
the
iconAwesome
attribute instead of
icon
.
Both
icon
and
iconAwesome
attributes, require the icon name as value the icon name without the trailing glyphicon- prefix and fa-
prefix respectively.
In the example below, the rightmost button has the
iconAwesome="thumbs-up"
attribute.
Both Fontawesome icons and Glyphicons can be decorated with modifiers:
You can put arbitrary content in the caption of the command button. You aren't limited to simple icons and text.
The lower row of the example above shows partial processing. Sometimes you don't want to submit an entire form to the server.
In our example you can't send the first name unless you've filled the last name, too, because of the constraint violation
which prevents the values from being sent to the server. Partial submit allows you to send parts of the form to the server
and to validate and process them independently from the rest of the form. Note that this example "forgets" the changes
of the "last name" input field when you submit the first name. Usually, you'll avoid this by using update="@form:firstname"
instead of updating the entire form.
immediate
since 0.9.1<b:commandButton />
supports the immediate
attribute, both in AJAX and non-AJAX requests.
This allows you to call a backend bean method even if the violation constraints are violated. The example below
allows you to start a new game no matter if the input field contains a legal value or not. The BootsFaces
ajax methods like onclick
execute the validations (but are executed even if there are validation
constraints), while the traditional actionListeners
bypass validation completely.
The classical usecase of the immediate
flag is the "cancel" button. Obviously, you don't
want to force the user to input correct data before they can cancel their input.
You can pass parameters to <b:commandButton />
in three different ways:
Click a button to pass the parameter.
You can use all the attributes controlling the responsive behaviour of <b:column />
also with <b:commandButton />
. Note that this is equivalent to putting it into a
<b:column />
. In particular, the the CSS styles are inside the column div.
Breaking change with version 1.1.0: Until BootsFaces 1.0.2, the generated HTML code
didn't comply to the rules of Bootstrap. This approach worked, but the commandButtons bleed into the padding
of their container. In other words, the commandButtons were to wide. BootsFaces 1.1.0 fixes this. If your CSS
rules use the id of the commandButton, you might have to modify the selector of the rule to #id > commandButton
.
You can play also with col-*-*, visible and hidden attribute, as any bootstrap elements. For example:
Attribute | Default value | Description |
---|---|---|
accesskey | (none) | Access key to transfer focus to the input element. |
action | (none) | The button action, this can be method expression or a string outcome. |
action-listener actionListener (alternative writing) |
(none) | A method expression that refers to a method with this signature: void methodName(Action-Event). |
ajax | false | Whether the Button submits the form with AJAX. |
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. |
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). |
disabled | false | Boolean value to specify if the button is disabled. |
display | block | If you use the "visible" attribute, the value of this attribute is added. Legal values: block, inline, inline-block. Default: block. |
hidden | (none) | This column is hidden on a certain screen size and below. Legal values: lg, md, sm, xs. |
icon | (none) | Button Icon, can be one of the Bootstrap icon names. Alignment can be specified with icon-align attribute. |
icon-align iconAlign (alternative writing) |
(none) | Alignment can be right or left. |
icon-awesome iconAwesome (alternative writing) |
(none) | Font Awesome Icon to show in this CommandButton, can be one of the Font Awesome icon names. Alignment can be specified with the icon-align attribute. |
icon-brand iconBrand (alternative writing) |
false | Use the free brand font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0. |
icon-flip iconFlip (alternative writing) |
(none) | Flip the icon: can be H (horizontal) or V (vertical). |
icon-inverse iconInverse (alternative writing) |
false | Switch the icon from black-on-white to white-on-black. |
icon-light iconLight (alternative writing) |
false | Use the paid 'light' font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0. |
icon-pulse iconPulse (alternative writing) |
false | Boolean value: if true the icon will rotate with 8 discrete steps. |
icon-regular iconRegular (alternative writing) |
false | Use the paid 'regular' font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0. |
icon-rotate iconRotate (alternative writing) |
(none) | Rotate 90 degrees the icon: Can be L,R. |
icon-size iconSize (alternative writing) |
(none) | Icon Size: legal values are lg (=133%), 2x, 3x, 4x, 5x. If you're using Fontawesome 5, also 6x, 7x, 8x, 9, 10x, xs (=75%), and sm (=87.5%) are allowed. |
icon-solid iconSolid (alternative writing) |
false | Use the free font of FontAwesome 5. As a side effect, every FontAwesome icon on the same page is switched to FontAwesome 5.2.0. By default, the icon set is the older version 4.7.0. |
icon-spin iconSpin (alternative writing) |
false | Boolean value: if true the icon will spin. |
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. |
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. |
look | (none) | Look of the Button, can be primary, block, info, success, warning, important, danger. If not specified, Standard gray button with gradient is rendered. |
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. |
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. |
onblur | (none) | Client side callback to execute when input element loses focus. |
onchange | (none) | Client side callback to execute when input element loses focus and its value has been modified since gaining focus. |
onclick | (none) | The onclick attribute. |
oncomplete | (none) | JavaScript to be executed when ajax completes. |
ondblclick | (none) | Client side callback to execute when input element is double clicked. |
onerror | (none) | JavaScript to be executed when ajax results on an error (including both network errors and Java exceptions). |
onfocus | (none) | Client side callback to execute when input element receives focus. |
onkeydown | (none) | Client side callback to execute when a key is pressed down over input element. |
onkeypress | (none) | Client side callback to execute when a key is pressed and released over input element. |
onkeyup | (none) | Client side callback to execute when a key is released over input element. |
onmousedown | (none) | Client side callback to execute when a pointer input element is pressed down over input element. |
onmousemove | (none) | Client side callback to execute when a pointer input element is moved within input element. |
onmouseout | (none) | Client side callback to execute when a pointer input element is moved away from input element. |
onmouseover | (none) | Client side callback to execute when a pointer input element is moved onto input element. |
onmouseup | (none) | Client side callback to execute when a pointer input element is released over input element. |
onselect | (none) | Client side callback to execute when text within input element is selected by user. |
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. |
rendered | false | Boolean value to specify the rendering of the component, when set to false the component will not be rendered. |
size | (none) | Size of the button, can be large ('lg'), small ('sm'), or tiny ('xs'). If not specified, standard size button is rendered. |
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 this element. |
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". |
type | (none) | The button type, can be submit, button, reset ; default submit. |
update | (none) | Component(s) to be updated with ajax. |
value | (none) | Optional button caption. |
visible | (none) | This column is shown on a certain screen size and above. Legal values: lg, md, sm, xs. |
A <b:commandButton />
is rendered as an HMTL <button />
bearing the CSS class btn
.
Depending on the value of the look
attribute, the button also bears one of the CSS classes btn-primary
,
btn-block
,
btn-info
,
btn-success
,
btn-warning
,
btn-important
or
btn-danger
.