Modals

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.

Triggering Modals

You have four ways to create a Button that triggers a Modal:

• Using HTML markup - a styled <a> tag with href and data attributes.
• Using HTML markup - a styled <button> tag with two data attributes.
• Using JSF BootsFaces markup - a <b:button> tag with passthrough data attributes and a little javascript to prevent click event.
• Using JavaScript. This is the most flexible version: you can use arbitrary jQuery selectors instead of ids, and you aren't limited to buttons.

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.

Troubleshooting: Modal and AJAX

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.

Troubleshooting: use CSS classes instead of ids

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.

Opening a modal dialog when entering the JSF view

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:

Alternatively, you can use the pass-through attributes that have been introduced with JSF 2.2:

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".

Displaying a <b:growl /> above a modal

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:

Form validation in a modal

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:

Datatables in a modal

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.

Reference section