Frontfire documentation

Modal plugin

Version 2.1.0

Frontfire UI provides a modal panel that overlays the page and can be used to display important messages that must be confirmed before proceding with anything else on the page, or to display details about something on-demand without using page layout space.

This plugin is available in the Minimal and Complete bundles.

Description

A modal is an element that overlays the page, shows a message or other content and provides buttons to let the user make a decision. A dialog box would be another name for it. The modal panel cannot be moved on the page, it always stays in the centre. The modal content can be freely defined in an HTML element with the modal CSS class which applies basic modal styles and makes the element invisible at first.

The modal can be customised with the CSS variables that start with “--modal-”.

To open a modal element, call the modal() plugin function on the element to show as modal. The function takes the options as its single object argument. The options are optional and can alternatively be specified as data-opt HTML attributes with the modal HTML element.

There is also a static Frontfire.modal() method that creates and opens a modal without an existing element in the document. It is described below.

Example

Result: Not yet opened

Wide modals

The modal container element is limited to 80% of the page width by default, except on small screens. To use the full window width, also add the wide CSS class to the modal element.

Full-page modals

Extensive UI layouts that need to show a lot of content, like longer selection lists with additional information, could use a very large modal. To provide that space, add the full-page CSS class to the modal element. It expands the width just as for the wide class, but also does that for the height symmetrically.

The modal may now be higher than its content needs to be, as can be seen in the following simple example. To use that space, it is recommended to also use the flexLayout option and provide a suitable content layout.

Modal title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin commodo et ante sed placerat. Phasellus ipsum neque, ultricies eu mattis ut, euismod in sapien. Sed ultricies a leo vitae fermentum. Fusce nulla lectus, suscipit sit amet eleifend a, pulvinar ac ante. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Quisque magna urna, vestibulum id dui ac, suscipit euismod turpis. Etiam eget pretium nisl. Sed a hendrerit erat, at sagittis nisi. Nullam ornare dapibus velit, ut lobortis lectus porta viverra. Cras et risus ex.

Options

The following options are available:

Name Type Description Default
cancelable Boolean Indicates whether the modal is closed when clicking anywhere outside of it or pressing Esc. This also shows a close button in the modal overlay. true
closeTooltip String The tooltip text for the close button. ""
defaultAction Function The action to execute when the Enter key was pressed. None
defaultButton Boolean Indicates whether the first default button is clicked when the Enter key was pressed. False
dimBackground Boolean Indicates whether the page background is dimmed while the modal is open. true

defaultButton added in v2.1.0

Plugin properties

This plugin provides properties to access the modal state.

isOpen

Determines whether the modal is currently open. This property cannot be written.

if (F("#modal").modal.isOpen) { // ... }

Plugin methods

This plugin provides methods to control the open modal.

close

Closes the selected modal.

F("#modal").modal.close();

Plugin events

This plugin triggers events for the modal.

closing

Triggered when the modal is about to close. This event can be cancelled by calling event.preventDefault() to keep the modal open.

close

Triggered when the modal is closed.

Static modal function

Besides opening a modal from a selected (existing) HTML element, there is another method to open a modal without any preparations. The static Frontfire.modal() plugin function creates and opens a modal from the data that was passed to it. This method accepts the options as described above as a single object argument. Additional options (see below) are used to define the content of the generated modal element.

If a string is passed as first argument, it is displayed as text with an “OK” button.

The method returns a Promise that resolves with the clicked button’s result, or undefined if the modal was closed otherwise. The Promise has an additional cancel() method to close the modal before a user interaction.

Result: Not yet opened

Additional options

In addition to the modal options listed above, these options are available for the static method:

Name Type Description Default
content Node The element to display as modal content. undefined
html String The message HTML content to display. undefined
text String The message text to display. undefined
buttons Array The buttons to display in the modal. undefined
buttons[].text String The button text. undefined
buttons[].icon String The CSS class of an <i> element displayed before the text. undefined
buttons[].iconText String The text content of an <i> element displayed before the text. undefined
buttons[].className String Additional CSS classes for the button. undefined
buttons[].result any The result value of the button. undefined
className String Additional CSS class names for the modal element. undefined
language String The language to use for default buttons (see below). Page language
flexLayout Boolean Specifies whether the modal container uses a flex layout instead of an overflow scoll. The options.content will not be wrapped in a new container. Use this if you have your own scrolling area in the content. false

flexLayout option added in v2.1.0

The first button with the default CSS class is focused initially. Pressing the Enter key will click that button.

Instead of explicitly defining all buttons and their properties, a set of quick predefined buttons is available. Specify one of the following strings as the buttons option to use them.

Value Description
OK OK default button (result: true)
OK cancel OK default button (result: true)
Cancel transparent button (result: false)
cancel Cancel transparent button (result: false)
YES no Yes default button (result: true)
No button (result: false)
yes NO Yes button (result: true)
No default button (result: false)
Any other value Button with the value as text (result: true)

"cancel" buttons value added in v2.1.0

If no language is specified, the language is determined by the lang attribute of the document root element (<html>). Currently, the following languages are supported. Specifying a different language will return English names.

Confirmation modals

Some buttons better ask for a confirmation when clicked. This is to avoid a dangerous action if it was accidentally clicked, like deleting some data or shutting down a service.

To ask for confirmation when clicked, call the confirm() plugin function on the element that will be clicked. The function takes the options as its single object argument. The options are optional and can alternatively be specified as data-opt HTML attributes with the source HTML elements.

This method must be called before adding other click event handlers because it will cancel the event at the first time! When the user confirmed the action, another click event is triggered and this time not cancelled.

Clicked button: None yet

Example

The confirmation feature is not applied automatically with a standard CSS class because it is expected that you will set custom or localised texts in your script. You can use different CSS classes to assign different standard texts in a central place. As an example, for all delete buttons in your application, you could use the confirm-delete CSS class to set a standard text and icon for the confirm button and only provide a specific message in the delete button’s data-opt-question attribute. A single JavaScript call will then apply an appropriate confirmation to all delete buttons:

Options

The following options are available:

Name Type Description Default
question String The confirmation question to present in the modal. "Please confirm the action."
confirmText String The text of the confirm button. "Confirm"
confirmIcon String The CSS class of an <i> element displayed before the text of the confirm button. None
confirmIconText String The text content of an <i> element displayed before the text of the confirm button. None
confirmClassName String Additional CSS classes for the confirm button. "caution"
cancelText String The text of the cancel button. "Cancel"
cancelIcon String The CSS class of an <i> element displayed before the text of the cancel button. None
cancelIconText String The text content of an <i> element displayed before the text of the cancel button. None
cancelClassName String Additional CSS classes for the cancel button. "transparent"
callback Function A function that is called when the user has clicked on the confirmation button of the modal. It is called with the clicked element as single argument. If the function returns a value, it overrides the boolean confirmation status. None