Class: IMatchModals

IMatchModals

This class implements frequently used modals (dialog boxes) based on the modal concept in Bootstrap 3.

Include File

<script src="/system/imatch/imatch-modals.js"></script>

Notes

Bootstrap 3 and FontAwesme 4 (Older Apps)

You need to include this in your index.html:
Requires /system/bootstrap/dist/js/bootstrap.min.js.
Requires /system/font-awesome/css/font-awesome.min.css.

Bootstrap 4 and FontAwesome 5

You need to include this in your index.html:
Requires /system/bootstrap-4/js/bootstrap.bundle.min.js.
Requires /system/font-awesome-5/webfonts/css/fontawesome-all.min.css".
Then you have to explicitly specify the icons when opening modals.
Note: Only one modal can be open at a time.

Bootstrap and FontAwesome Versions

The bsVersion parameter for the constructor controls which Bootstrap-Version should be used.
The default is 3 (Bootstrap 3, older). Use 4 to use the modern Bootstrap 4 modals.
Note: The templates for Bootstrap 4 use FontAwesome 5 icons and hence require the font-awesome-5 include (see above).

Translating Modals

If you include /system/imatch/imatch-translate.js in your code, the modals created by this class will be automatically translated. You can then use imt-* attriubutes to let your modals translate automatically. See IMatchTranslate for more info.

Your Own Templates

The modal templates use Bootstrap modal classes and some CSS classes defined in the imatch.css file. You can override these in your own CSS file to make the modals look different.
If you create your own templates, specify the template file as a parameter to the IMatchModals#showModal method. Creating your own templates allows you to use more complex modals, dialog boxes etc.


new IMatchModals()

Methods


closeModal()

This method closes any open modal.


hasModal() → {Bool}

Returns:

true when a modal is currently open.

Type
Bool

showMessageBoxOK()

Displays a message box with a title, text and an OK button.
Note that this function does not block execution, it just displays an overlay and disables the rest of the DOM.
The JavaScript continues to execcute. If you want to run code after the modal has been closed, use the callback parameter.

Parameters:
Name Type Argument Default Description
params.title String <optional>

The title to display. If this is not specified, the title IMatch is displayed.

params.headline String <optional>
empty

The headline to display. This can be text or HTML. It is wrapped in a <h4>

params.content String <optional>
empty

The content to display. This can be text or HTML. It is wrapped in a <div>.

params.okCaption String <optional>
'OK'

The caption to use for the OK button. This can be text or HTML.

params.icon String <optional>
'fa fa-question-circle fa-3x'

The FontAwesome icon to use.

params.modalClass= String <optional>

AN optional class to add to the div with the class .modal-class that wrapps the dialog.

params.callback= String <optional>

The callback function to call when the user closes the modal with the OK button or the X button at the top.

params.parent= String <optional>

A jQuery selector to find the parent to attach the modal to. If no parent is specified, <body> is used.

Example
// The simplest message box, just a headline and a text:     
let m = new IMatchModals();
m.showMessageBoxOK({
    headline: 'Hello',
    content: 'This is an IMatch modal.'
});

// Using custom icons, button caption and a callback function:
let m = new IMatchModals();
m.showMessageBoxOK({
    headline: 'Hello',
    content: 'This is an IMatch modal.',
    okCaption: 'Close',
    icon: 'fa fa-bolt fa-3x',
    callback: () =>  {
        console.log('Modal now closed. Do some work.');
    },
    parent: '#app-container'
});

showErrorBox()

Displays an error message box with a title, text and an OK button.
Note that this function does not block execution, it just displays an overlay and disables the rest of the DOM.
The JavaScript continues to execcute. If you want to run code after the modal has been closed, use the callback parameter.

Parameters:
Name Type Argument Default Description
params.title String <optional>

The title to display. If this is not specified, the title IMatch is displayed. If this is an empty string, the header is hidden.

params.headline String <optional>
empty

The headline to display. This can be text or HTML. It is wrapped in a <h4>

params.content String <optional>
empty

The content to display. This can be text or HTML. It is wrapped in a <div>.

params.additionalInfo String <optional>
empty

Additional info to display, e.g., a server response.

params.okCaption String <optional>
'OK'

The caption to use for the OK button. This can be text or HTML.

params.icon String <optional>
'fa fa-exclamation-triangle fa-3x'

The FontAwesome icon to use.

params.modalClass= String <optional>

AN optional class to add to the div with the class .modal-class that wrapps the dialog.

params.headerColor= String <optional>

The optional color to use for the modal header. Use something like '#800000' for a dramatic effect.

params.callback= function <optional>

The callback function to call when the user closes the modal with the OK button or the X button at the top.

parems.onInitDone function <optional>

This function is called after the modal has been loaded and translated but before it is displayed.

params.parent= String <optional>

A jQuery selector to find the parent to attach the modal to. If no parent is specified, <body> is used.

Example
let m = new IMatchModals();
m.showErrorBox({
    headline: 'Snap',
    content: 'Something has crashed.',
    icon: 'fa fa-frown fa-3x',   or 'far fa-frown fa-3x' for FA 4
    callback: () => {
    },
});

showMessageBoxYesNo()

Displays a message box with a title, text and OK and Cancel button.
This can be used for classic OK/Cancel dialog boxes or (with custom button captions) for Yes/No, True/False or similar modals.
Note that this function does not block execution, it just displays an overlay and disables the rest of the DOM.
The JavaScript continues to execcute. If you want to run code after the modal has been closed, use the callback parameter.

Parameters:
Name Type Argument Default Description
params.title String <optional>
IMatch

The title to display. If this is not specified, the title IMatch is displayed. If this is an empty string, the header is hidden.

params.headline String <optional>
empty

The headline to display. This can be text or HTML. It is wrapped in a <h4>

params.content String <optional>
empty

The content to display. This can be text or HTML. It is wrapped in a <div>.

params.okCaption String <optional>
'OK'

The caption to use for the OK button. This can be text or HTML.

params.cancelCaption String <optional>
'Cancel'

The caption to use for the Cancel button. This can be text or HTML.

params.icon String <optional>
'fa fa-question-circle fa-3x'

The FontAwesome icon to use.

params.modalClass= String <optional>

AN optional class to add to the div with the class .modal-class that wrapps the dialog.

params.okCallback= function <optional>

The callback function to call when the user closes the modal with the OK button.

params.cancelCallback= function <optional>

The callback function to call when the user closes the modal with the Cancel button or the X button at the top.*

parems.onInitDone function <optional>

This function is called after the modal has been loaded and translated but before it is displayed.

params.parent= String <optional>

A jQuery selector to find the parent to attach the modal to. If no parent is specified, <body> is used.

Example
let m = new IMatchModals();
m.showMessageBoxYesNo({
    headline: 'Delete File',
    content: 'Do you really want to delete this file?',
    okCaption: 'Yes',
    cancelCaption: 'No',
    okCallback: () =>
    {
        console.log('User clicked yes.');
    },
    cancelCallback: () =>
    {
        console.log('User clicked Cancel or closed the modal with X.');
    }
});

showModalParams(params)

Parameters:
Name Type Description
params Object

The params to use with showModal.

Properties
Name Type Argument Default Description
templateFileName string

The relative file name of the template file to load.

selector string <optional>
'body'

A jQuery selector to find the parent element to append the modal DOM to. You can specify something like '#app-container' to append the modal to the DOM of the element with the id app-container.

onOK function <optional>

This function is called when the user presses OK.

onCancel function <optional>

This function is called when the user presses Cancel

onInitDone function <optional>

This function is called after the modal has been loaded and translated but before it is displayed.

onValidate function <optional>

If specified, this callback is called when the user clicks on the OK button. If the callback returns true, the modal is closed and onOK() is called.

onDestroyed function <optional>

If specified, this callback is called when the modal (and the corresponding DOM) is destroyed.


showModal(templateFileName [, selector] [, onOK] [, onCancel] [, onInitDone] [, onValidate] [, onDestroyed] [, onShow])

This function loads the specified template and displays it.
This is the core function used by the other showMessageBox... functions in this class. You can use it to load and display your own modal templates. Use a path relative to your app as the templateFileName in this case.

Parameters:
Name Type Argument Default Description
templateFileName string

The relative file name of the template file to load.

selector string <optional>
'body'

A jQuery selector to find the parent element to append the modal DOM to. You can specify something like '#app-container' to append the modal to the DOM of the element with the id app-container.

onOK function <optional>

This function is called when the user presses OK.

onCancel function <optional>

This function is called when the user presses Cancel

onInitDone function <optional>

This function is called after the modal has been loaded and translated but before it is displayed.

onValidate function <optional>

If specified, this callback is called when the user clicks on the OK button. If the callback returns true, the modal is closed and onOK() is called.

onDestroyed function <optional>

If specified, this callback is called when the modal (and the corresponding DOM) is destroyed.

onShow function <optional>

If specified, this callback is called when the modal becomes visible. Use this for things like setting a focus.
You can use this to make modifications to the modal DOM after the modal has been added.