315 lines
7.7 KiB
ReStructuredText
315 lines
7.7 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
|
|
|
.. _feature-80579:
|
|
|
|
===============================================
|
|
Feature: #80579 - Improved JavaScript Modal API
|
|
===============================================
|
|
|
|
See :issue:`80579`
|
|
|
|
Description
|
|
===========
|
|
|
|
To improve the usability and flexibility for a unified handling of overlays in
|
|
the backend we're opening the existing API for modals to be more flexible and
|
|
adjustable to your needs for advanced usage. With the introduction of the
|
|
advanced API it is now possible to pass configuration by json object. This
|
|
enables more easy configuration and better fallback if the modal is not
|
|
correctly configured.
|
|
|
|
For a unified experience all modals are now centered by default, will kept in
|
|
place automatically and are available in different sized depending on your needs.
|
|
In addition to this there is also a new type for loading content into an
|
|
iframe. Buttons have now full support for the TYPO3 Icon API and data
|
|
attributes that also can set by configuration.
|
|
|
|
Advanced API
|
|
------------
|
|
|
|
Unlike the existing api functions like :js:`Modal.confirm`, :js:`Modal.loadUrl` or
|
|
:js:`Modal.show`, :js:`Modal.advanced` uses a JavaScript object instead of fixed
|
|
parameters.
|
|
|
|
.. code-block:: javascript
|
|
|
|
require([
|
|
'jquery',
|
|
'TYPO3/CMS/Backend/Modal'
|
|
], function ($, Modal) {
|
|
|
|
var configuration = {
|
|
type: Modal.types.iframe,
|
|
title: title,
|
|
content: url,
|
|
size: Modal.sizes.large,
|
|
callback: function(currentModal) {
|
|
currentModal.find('.t3js-modal-body')
|
|
.addClass('custom-css-class');
|
|
}
|
|
};
|
|
Modal.advanced(configuration);
|
|
|
|
});
|
|
}
|
|
|
|
|
|
Configuration Options
|
|
---------------------
|
|
|
|
Type
|
|
^^^^
|
|
|
|
The :js:`type` will define the behaviour of content loading, and only accepts
|
|
:js:`Modal.types.ajax`, :js:`Modal.types.iframe` and the default :js:`Modal.types.default`.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
type: Modal.types.iframe,
|
|
content: url || content
|
|
};
|
|
|
|
Modal.types.default
|
|
Default will display static content set in the option `content`.
|
|
|
|
Modal.types.ajax
|
|
Content will be grabbed from a url set in the option `content`
|
|
|
|
Modal.types.iframe
|
|
Url provided in the option `content` will be loaded in an iframe in the modal.
|
|
Also it will automatically set the title from the contained document.
|
|
|
|
|
|
Title
|
|
^^^^^
|
|
|
|
The `title` will be display above the modal content. For the type
|
|
:js:`Modal.types.iframe` this option will have no effect. As soon as the content
|
|
from the iframe is loaded, the title will be replaced with title of the
|
|
contained document. The default will set the title to "Information".
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
title: 'My Title'
|
|
};
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
Content
|
|
^^^^^^^
|
|
|
|
The `content` accepts only strings that can be either a HTML or a url for types
|
|
:js:`Modal.types.ajax` and :js:`Modal.types.iframe`. The default will show a warning
|
|
that there is a possible misconfiguration of the modal.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configurationStatic = {
|
|
type: Modal.types.default,
|
|
content: 'My Title'
|
|
};
|
|
Modal.advanced(configurationStatic);
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configurationAjax = {
|
|
type: Modal.types.ajax,
|
|
content: 'http://www.google.de/'
|
|
};
|
|
Modal.advanced(configurationAjax);
|
|
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configurationIframe = {
|
|
type: Modal.types.iframe,
|
|
content: 'http://www.google.de/'
|
|
};
|
|
Modal.advanced(configurationIframe);
|
|
|
|
|
|
Severity
|
|
^^^^^^^^
|
|
|
|
Severity is used to change the appearance of the modal window to represent a
|
|
contextual state like success, information, warning or danger. The default is
|
|
:js:`Severity.notice`. Only options provided by the :js:`Severity` object will be
|
|
accepted.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
severity: Severity.info,
|
|
};
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
Buttons
|
|
^^^^^^^
|
|
|
|
Defined buttons will be display displayed at the bottom of the modal window.
|
|
The configuration accepts an array of single button definitions.
|
|
|
|
.. code-block:: javascript
|
|
|
|
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);
|
|
|
|
|
|
text
|
|
Text that will be displayed in the button
|
|
|
|
name
|
|
Value of the name attribute of the button
|
|
|
|
icon
|
|
Name of the icon that will be displayed in front of the text
|
|
|
|
active
|
|
Activated button after opening the modal window
|
|
|
|
btnClass
|
|
Additional css class that will be added to the button
|
|
|
|
dataAttributes
|
|
Object of data attributes that will be added to the button
|
|
|
|
trigger
|
|
Callback function that will be triggered then the button is clicked
|
|
|
|
|
|
Style
|
|
^^^^^
|
|
|
|
The ``style`` option will change the appearance of the modal like the ``severity``
|
|
both without contextual meaning. The default option is :js:`Modal.styles.light`.
|
|
The second available option is :js:`Modal.styles.dark` will override all contextual
|
|
styling.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
style: Modal.styles.default
|
|
}
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
Size
|
|
^^^^
|
|
|
|
While the modal itself adapts to the window, there are several options available
|
|
to limit the maximal size of the modal. The sizes :js:`Modal.sizes.small` and the
|
|
default :js:`Modal.sizes.default` will automatically adapt to the content and are only
|
|
limited to the width of the modal. :js:`Modal.sizes.large` and :js:`Modal.sizes.full`
|
|
are designed to contain a undefined length of content in a fixed sized modal.
|
|
These are suited best for :js:`Modal.types.ajax` or :js:`Modal.types.iframe` content.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
size: Modal.sizes.large
|
|
}
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
Modal.sizes.small
|
|
Limited to 400px width
|
|
|
|
Modal.sizes.default
|
|
Limited to 600px width
|
|
|
|
Modal.sizes.large
|
|
Limited to 800px width and 600px height
|
|
|
|
Modal.sizes.full
|
|
Limited to 1800px width and 1200px height
|
|
|
|
|
|
Additional CSS Classes
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The option `additionalCssClasses` accepts an array of css classes that will be
|
|
added to the modal frame.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
additionalCssClasses: [
|
|
'class1',
|
|
'class2'
|
|
]
|
|
}
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
Callback
|
|
^^^^^^^^
|
|
|
|
Callback function that will be called after the modal is processed.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
callback: function(currentModal) {
|
|
currentModal.find('.t3js-modal-body')
|
|
.addClass('custom-css-class');
|
|
}
|
|
}
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
Callback after ajax processing
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Callback function that will be called after the ajax call has been done and
|
|
the response added to the desired location. This option is only available for
|
|
type :js:`Modal.types.ajax`.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
type: Modal.types.ajax,
|
|
ajaxCallback: function() {
|
|
do();
|
|
}
|
|
}
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
Target for ajax response
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The ajax response will be added to the body of the particular modal window by
|
|
default but can be set to a different selector if necessary. This option is only
|
|
available for type :js:`Modal.types.ajax`.
|
|
|
|
.. code-block:: javascript
|
|
|
|
var configuration = {
|
|
type: Modal.types.ajax,
|
|
ajaxTarget: '.t3js-modal-footer'
|
|
}
|
|
Modal.advanced(configuration);
|
|
|
|
|
|
.. index:: JavaScript, Backend
|