TYPO3 v15 dev-main snapshot ()
This commit is contained in:
@@ -0,0 +1,314 @@
|
||||
.. 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
|
||||
Reference in New Issue
Block a user