Modals¶
Changed in version 12.0: The modal API provided by the module @typo3/backend/modal.js
has been
adapted to be backed by a custom web component and therefore gained an updated,
stateless interface. See also section Migration.
Actions that require a user's attention must be visualized by modal windows.
TYPO3 provides an API as basis to create modal windows with severity
representation. For better UX, if actions (buttons) are attached to the modal,
one button must be a positive action. This button should get a btnClass
to highlight it.
Modals should be used rarely and only for confirmations. For information that does not require a confirmation the Notification API (flash message) should be used.
For complex content, like forms or a lot of information, use normal pages.
API¶
Changed in version 12.0: The return type of all Modal.*
factory methods has been changed from
JQuery
to ModalElement
.
The API provides only two public methods:
TYPO3.Modal.confirm(title, content, severity, buttons)
TYPO3.Modal.dismiss()
Modal settings¶
- title¶
- Required
true
- Type
string
The title displayed in the modal
- content¶
- Required
true
- Type
string|jQuery
The content displayed in the modal
- severity¶
- Type
int
- Default
TYPO3.Severity.info
Represents the severity of a modal. Please see
TYPO3.Severity
.
- buttons¶
- Type
object[]
Actions rendered into the modal footer. If empty, the footer is not rendered. See section Modals on how to configure the buttons.
- staticBackdrop¶
- Type
bool
- Default
false
Controls whether a static backdrop should be rendered, which prevents closing the modal by clicking outside of it.
Button settings¶
- text¶
- Required
true
- Type
string
The text rendered into the button.
- trigger / action¶
- Required
true
- Type
function
Callback that is triggered on button click - either a simple function or
DeferredAction
/ImmediateAction
- active¶
- Type
bool
Marks the button as active. If true, the button gets the focus.
- btnClass¶
- Type
string
The CSS class for the button.
Changed in version 12.0: The Button
property dataAttributes
has been removed without
replacement, as the functionality can be expressed via Button.name
or Button.trigger
and is therefore redundant.
Data Attributes¶
It is also possible to use data
attributes to trigger a modal,
for example on an anchor element, which prevents the default behavior.
data-title
The title text for the modal.
data-bs-content
The content text for the modal.
data-severity
The severity for the modal, default is
info
(seeTYPO3.Severity.*
).data-href
The target URL, default is the
href
attribute of the element.data-button-close-text
Button text for the close/cancel button.
data-button-ok-text
Button text for the ok button.
class="t3js-modal-trigger"
Marks the element as modal trigger.
data-static-backdrop
Render a static backdrop to avoid closing the modal when clicking it.
Example:
<a
href="delete.php"
class="t3js-modal-trigger"
data-title="Delete"
data-bs-content="Really delete?"
>
delete
</a>
Examples¶
A basic modal (without anything special) can be created this way:
TYPO3.Modal.confirm('The title of the modal', 'This the the body of the modal');
A modal as warning with button:
TYPO3.Modal.confirm('Warning', 'You may break the internet!', TYPO3.Severity.warning, [
{
text: 'Break it',
active: true,
trigger: function() {
// break the net
}
}, {
text: 'Abort!',
trigger: function() {
TYPO3.Modal.dismiss();
}
}
]);
A modal as warning:
TYPO3.Modal.confirm('Warning', 'You may break the internet!', TYPO3.Severity.warning);
Action buttons in modals created by the TYPO3/CMS/Backend/Modal
module may
make use of TYPO3/CMS/Backend/ActionButton/ImmediateAction
and
TYPO3/CMS/Backend/ActionButton/DeferredAction
.
As an alternative to the existing trigger
option, the option
action
may be used with an instance of the previously mentioned modules.
Modal.confirm('Header', 'Some content', Severity.error, [
{
text: 'Based on trigger()',
trigger: function () {
console.log('Vintage!');
}
},
{
text: 'Based on action',
action: new DeferredAction(() => {
return new AjaxRequest('/any/endpoint').post({});
})
}
]);
Activating any action disables all buttons in the modal. Once the action is done, the modal disappears automatically.
Buttons of the type DeferredAction
render a spinner on activation
into the button.
A modal with static backdrop:
import Modal from '@typo3/backend/modal';
Modal.advanced({
title: 'Hello',
content: 'This modal is not closable via clicking the backdrop.',
size: Modal.sizes.small,
staticBackdrop: true
});
Templates, using the HTML class .t3js-modal-trigger
to initialize
a modal dialog are also able to use the new option by adding the
data-static-backdrop
attribute to the corresponding element.
<button class="btn btn-default t3js-modal-trigger"
data-title="Hello"
data-bs-content="This modal is not closable via clicking the backdrop."
data-static-backdrop>
Open modal
</button>
Migration¶
Given the following fully-fledged example of a modal that uses custom buttons,
with custom attributes, triggers and events, they should be migrated away
from JQuery
to ModalElement
usage.
Existing code:
var configuration = {
buttons: [
{
text: 'Save changes',
name: 'save',
icon: 'actions-document-save',
active: true,
btnClass: 'btn-primary',
dataAttributes: {
action: 'save'
},
trigger: function() {
Modal.currentModal.trigger('modal-dismiss');
}
}
]
};
Modal
.advanced(configuration)
.on('hidden.bs.modal', function() {
// do something
});
Should be adapted to:
const modal = Modal.advanced({
buttons: [
{
text: 'Save changes',
name: 'save',
icon: 'actions-document-save',
active: true,
btnClass: 'btn-primary',
trigger: function(event, modal) {
modal.hideModal();
}
}
]
});
modal.addEventListener('typo3-modal-hidden', function() {
// do something
});