Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults.
Modal options
You can specify a header with the title
attribute. Modals have a dismiss button(a cross) in the upper right corner by default.
The <b:modal>
tag has also a facet with name footer
where you can add buttons for dismissing the modal or for other actions.
Notice that the <b:button>
tag must have the dismiss="modal"
attribute in order to dismiss the modal when clicked.
You have four ways to create a Button that triggers a Modal:
<a>
tag with href and data attributes.<button>
tag with two data attributes.<b:button>
tag with passthrough data attributes and a little javascript to prevent click event.Note: if your intended use is to trigger a data submission that shows the results in a Modal, then have a look at the commandButton documentation.
The following example shows you how to use the four kinds of triggers.
Overlapping modals are not supported: be sure not to open a modal while another is still visible. Showing more than one modal at a time requires custom code.
Sometimes developers report that the modal dialog is closed after clicking the "OK" button, but the screen remains gray and inactive. This usually happens if you're using an AJAX update replacing the modal. So the JavaScript variables point to a modal window which ceased to exist.
You can solve the bug by reducing the update region. Make sure that the AJAX update only updates the content of the modal. You can also update regions outside the modal. The bottom line is that the modal itself remains unchanged.
Using ids
is always a bit tricky in JSF.
Don't put your modal dialog into a form. If you do, be aware that the id is modified. The href
of the b:button
refers
to the id
in the HTML code, not to the id
of the source code. JSF prepends the ids of the parent containers
to the id
of b:modal
.
In general, it's a better idea to use a pseudo CSS class instead of an id
. That's a styleClass
that may or may not have
CSS instructions applied to it. Pure pseudo CSS classes don't influence the layout at all. They are simply a convenient alternative to ids. Instead
of writing href="#someId"
you can write href=".somePseudoClass"
. JSF never modifies CSS class names, so they are a good
alternative to using ids
. However, you have to use some JavaScript to activate the modal dialog using a CSS pseudo class, as the following example shows:
closable
and backdrop
By default, there's an x symbol which allows the user to close the modal. Set closable="false"
to suppress the close icon.
Users can close modal dialogs by hitting the ESC key unless you set close-on-escape="false"
.
Another default behavior of modal is that you can close a modal dialog by clicking somewhere outside the modal. Set backdrop="false"
to disable this feature.
If you don't want to open the modal dialog when a button is clicked, but already when the JSF view is opened, you can use an inline script to open the dialog programmatically:
Just in case you wonder why it doesn't suffice to add the pass-through attribute pt:data-show="true"
to the b:modal
:
By default, this attribute is already set to true
. It influences what happens when you call
$('.modalPseudoClass').modal();
(i.e. omitting the attribute 'show'
). If pt:data-show="false"
,
the data structure of the modal is initialized, but it remains invisible. If pt:data-show="true"
, the modal is also shown.
Calling $('.modalPseudoClass').modal('show');
or $('.modalPseudoClass').modal('hide');
overrides the default
setting defined by pt:data-show="true"
.
By default, growls are shown in a lower z-index level than the modal. In order to display the <b:growl /> properly
you have to raise its z-index
to 1050 or above, as shown in this example:
Often modals contains a form with validations. You'll want to check the validation rules before closing the form. If any validation is violated, you don't want to close the modal. Instead, you'd rather update the form with the error message.
You can achieve this by adding <b:fetchBeanInfo />
to the form. Plus, you need to add an oncomplete
listener closing the modal if the global flag validationFailed
is false
:
By default, modals are hidden. As a consequence, any <b:dataTable />
inside the modal is rendered incorrectly.
You can fix that by recalculating the datatable after showing the modal. You need the JavaScript approach for that. Just add the line
myDataTableWidgetVar.DataTable().responsive.recalc();
as shown in the example below.
If simpler approach is to set the flag scroll-horizontally="true"
. This adds a scrollbar to the table.
The advantage of this approach is that it works without JavaScript. The disadvantage is that it doesn't work with reponsive tables
using responsive="true"
. You can see the difference in the example below.
Attribute | Default value | Description |
---|---|---|
auto-update autoUpdate (alternative writing) |
false | Setting this flag updates the widget on every AJAX request. |
backdrop | true | By default, you can close a modal dialog by clicking somewhere outside the modal. Set backdrop="false" to disable this feature. |
closable | true | If true, the modal dialog can be closed by clicking the small cross in the upper right corner |
close-on-escape closeOnEscape (alternative writing) |
true | By default, users can close modal dialogs by hitting the ESC key. Set close-on-escape="false" to disable this feature. |
content-class contentClass (alternative writing) |
(none) | content-class is optional: if specified, the content will be displayed with this specific class |
content-style contentStyle (alternative writing) |
(none) | Inline style of the content area. |
header-class headerClass (alternative writing) |
(none) | The style class of the header is optional. If specified, it will add a CSS style class to the header. |
header-style headerStyle (alternative writing) |
(none) | The style of the header is optional. If specified, it will add the CSS style to the header. |
id | (none) | Unique identifier of the component in a namingContainer. |
rendered | false | Boolean value to specify the rendering of the component, when set to false the component will not be rendered. |
size | (none) | Modal's size. Possible values modal-sm, modal-lg |
style | (none) | Inline style |
style-class styleClass (alternative writing) |
(none) | Style class of this element. |
title | (none) | Bold title displayed in the modal's header. |
The optional facet footer
can be used to display buttons below a horizontal ruler, as shown in the example above.