Modals
Basic Modal
WebUI supports the creation of responsive model dialogs in 5 different sizes: small, medium, large, full and un-sized. Modal dialogs can be positioned in one of 9 different screen locations, these are: top left, top center, top right, middle left, middle center (default), middle right, bottom left, bottom center, and bottom right.
Modals are responsive out of the box, so the width and height will adjust according to the available screen area - this is so that a modal can never go off screen. As far as the modal content goes there is no special layout, so you can design your modal how you want it. However, it's always best to design your layout to suit the initial modal sizes. But if you need more height and you don't mind a vertical scrolling, then you can add as much as you wish.
The following example includes configured focus elements as well as making use of the focus trap control. For more information on using focus traps, see the Focus Trap section.
<div class="row text-bold text-sm">
<div class="col">
<button type="button" class="button-sm button-info" id="showModal1">Show Modal</button>
</div>
</div>
<div id="modal1" class="modal">
<div class="modal-md modal-auto-stretch accent-1-light">
<div class="text-mega place-top-right">
<a href="javascript:void(0)" class="modal-close button-link text-lg color-info color-hover-accent-4 margin-top-minus-xs-sm margin-left-minus-xs-sm fixed">✗</a>
</div>
<div class="modal-scroll-body min-height-three-quarters">
<div class="flex flex-direction-column height-full">
<div class="flex-initial pad-md">
<span class="text-xl text-bold">Modal Example</span>
</div>
<div class="flex-expand pad-md">
<div class="border-xs border-muted pad-md">
<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor
quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean
ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum
erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum,
eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis.</p>
<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor
quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean
ultricies mi vitae est. Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum
erat wisi, condimentum sed, commodo vitae, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum,
eros ipsum rutrum orci, sagittis tempus lacus enim ac dui. Donec non enim in turpis pulvinar facilisis.</p>
</div>
</div>
<div class="flex-initial flex justify-content-end gap-horizontal-sm pad-md">
<div><button type="button" class="button-sm button-success rounded-md" id="modal1OkButton">OK</button></div>
<div><button type="button" class="button-sm button-accent-4 rounded-md modal-close" id="modal1CancelButton">Cancel</button></div>
</div>
</div>
</div>
</div>
</div>
webui.ready( () => {
var modal1 = ui("#modal1").modalControl({
transitionDuration: 200,
closeFromBackdrop: true,
disablePageScrolling: true,
focusElement: "#modal1CancelButton",
focusReturnElement: "#showModal1"
});
ui("#showModal1").click( () => {
modal1.open();
});
var modal1FocusTrap = ui("#modal1").focusTrapControl({
firstFocusElement: "#modal1OkButton",
lastFocusElement: "#modal1CancelButton"
});
});
Modal Classes
Classes available in WebUI for modals.
| Class | Description |
|---|---|
| modal | Defines the modal container and backdrop. |
| modal-close | Specifies that the control will close the modal when activated. |
| modal-scroll-body | A container to wrap modal content and allow vertical scrolling without a scrollbar. |
Sizing Classes
The modal sizing classes are described below.
| Class | Description |
|---|---|
| model-sm | Specifies a small sized modal. |
| modal-md | Specifies a medium sized modal. |
| modal-lg | Specifies a large sized modal. |
| modal-full | Specifies a full screen modal. |
| modal-unsized | Specifies a modal that is sized according to its content. (Suitable for basic lightbox functionality). |
| modal-auto-stretch | Causes the modal height to stretch on small device viewports. |
Positioning Classes
NOTE: The default modal position is at the absolute center of the viewport unless the modal-unsized class is also used. Add one of the modal positioning classes from the options below to explicitly position an unsized modal.
| Class | Description |
|---|---|
| modal-top-left | Positions the modal at the top left of the viewport. |
| modal-top-center | Positions the modal at the top center of the viewport. |
| modal-top-right | Positions the modal at the top right of the viewport. |
| modal-middle-left | Positions the modal at the middle left of the viewport. |
| modal-middle-center | Positions the modal at the absolute center of the viewport. (Only required when modal-unsized class is also used). |
| modal-middle-right | Positions the modal at the middle right of the viewport. |
| modal-bottom-left | Positions the modal at the bottom left of the viewport. |
| modal-bottom-center | Positions the modal at the bottom center of the viewport. |
| modal-bottom-right | Positions the modal at the bottom right of the viewport. |
Modal Functions
The functions available for modals are described below.
| Function | Description |
|---|---|
| open() | Shows a modal. |
| close() | Closes a modal. |
| update(newSettings) | Updates the modal instance at runtime using the configuration settings. |
Modals can be closed by using the Esc key.
Modal FunctionsIt is important that the functions open and close are used if you want to open and close modal dialogs programatically as some background tasks need to be completed, such as disabling and re-enabling scrolling for the underlying page. However, within the modal you only need to add the class modal-close on controls that will close the modal.
Settings
Javascript settings available for the modal control.
| Setting | Description |
|---|---|
| closeFromBackdrop | Whether to allow the modal to be dismissed by clicking outside the modal. Can be true or false. Default: false. |
| disablePageScrolling | Whether to disable page scrolling while the modal is open. Default: true. |
| focusElement | The element or control to receive focus when the modal is opened. Default: null. |
| focusReturnElement | The element or control to receive focus when the modal is closed. Default: null. |
| transitionDuration | The time taken in milliseconds for the modal to fade in and out. An integer value. Default: 300. |
Displaying Images
Modals can also be used for displaying images. Use the modal-unsized class inner modal box to ensure the image always fits the modal window exactly while maintaining the original aspect ratio.
<div class="row text-bold text-sm">
<div class="col">
<button type="button" class="button-sm button-info" id="showModal2">Show Modal</button>
</div>
</div>
<div id="modal2" class="modal">
<div class="modal-unsized modal-middle-center accent-1-light">
<div class="text-mega place-top-right">
<a href="javascript:void(0)" class="modal-close button-link text-lg color-info color-hover-accent-4 margin-top-minus-xs-sm margin-left-minus-xs-sm fixed">✗</a>
</div>
<div><img src="images/pears.jpg" alt="picture" class="image"></div>
</div>
</div>
webui.ready( () => {
var modal2 = ui("#modal2").modalControl({
transitionDuration: 200,
closeFromBackdrop: true,
disablePageScrolling: true,
focusElement: null,
focusReturnElement: null
});
ui("#showModal2").click( () => {
modal2.open();
});
});
Component Update
Run-time Modal Updates
Settings specified for the modalControl instance can be updated programatically at run-time. See the following example, which sets the transitionDuration setting to 500 and the closeFromBackdrop setting to false. Use the restore button to revert the change.
<div class="row gap-md text-sm">
<div class="col">
<button type="button" class="button-sm button-info" id="showModal3">Show Modal</button>
</div>
<div class="col-fixed">
<button id="modalUpdateCommand" class="button-sm menu-button-info">Update</button>
</div>
<div class="col-fixed">
<button id="modalRestoreCommand" class="button-sm menu-button-info">Restore</button>
</div>
</div>
<div id="modal3" class="modal">
<div class="modal-unsized modal-middle-center accent-1-light">
<div class="text-mega place-top-right">
<a href="javascript:void(0)" class="modal-close button-link text-lg color-info color-hover-accent-4 margin-top-minus-xs-sm margin-left-minus-xs-sm fixed">✗</a>
</div>
<div><img src="images/pears.jpg" alt="picture" class="image"></div>
</div>
</div>
webui.ready( () => {
var modal3 = ui("#modal3").modalControl({
transitionDuration: 200,
closeFromBackdrop: true,
disablePageScrolling: true,
focusElement: null,
focusReturnElement: null
});
ui("#showModal3").click( () => {
modal3.open();
});
ui("#modalUpdateCommand").click( () => {
modal3.update({ transitionDuration: 500, closeFromBackdrop: false });
});
ui("#modalRestoreCommand").click( () => {
modal3.update({ transitionDuration: 200, closeFromBackdrop: true });
});
});
Functions
WebUI provides a single function that can be used to update the modal instance settings at runtime.
| Function | Description |
|---|---|
| update(newSettings) | Updates the modal instance at runtime using the configuration settings. |
Function Arguments
| Argument | Description |
|---|---|
| newSettings | An object literal containing a comma separated list of settings. |
Events
Modal Event Callbacks
There are 4 event callbacks that can be used, ui.modal.show.before, ui.modal.show.after, ui.modal.hide.before, and ui.modal.hide.after. The following script shows how to setup the event callbacks.
webui.ready(function() {
modal1.on("ui.modal.show.before", (e) => {
// Take some action
});
modal1.on("ui.modal.show.after", (e) => {
// Take some action
});
modal1.on("ui.modal.hide.before", (e) => {
// Take some action
});
modal1.on("ui.modal.hide.after", (e) => {
// Take some action
});
});