TYPO3 v15 dev-main snapshot ()

Documentation/Changelog/10.1/Feature-89061-IntroduceNotificationActions.rst

@@ -0,0 +1,95 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-89061:
+
+================================================
+Feature: #89061 - Introduce Notification Actions
+================================================
+
+See :issue:`89061`
+
+Description
+===========
+
+Notifications rendered by the :js:`TYPO3/CMS/Backend/Notification` module are now able to render action buttons. Each
+notification method (:js:`info()`, :js:`success()` etc) accepts an array of actions, each action is described by a
+:js:`label` and a pre-defined action type, containing a callback.
+
+However, notifications flagged with a duration will still disappear, unless an action is taken.
+
+.. important::
+
+   Such tasks must **never** be mandatory to be executed. This API is meant to suggest certain actions without enforcing
+   them. If a user is supposed to take immediate actions consider using modals instead.
+
+
+Example:
+
+.. code-block:: js
+
+   require([
+     'TYPO3/CMS/Backend/ActionButton/ImmediateAction',
+     'TYPO3/CMS/Backend/ActionButton/DeferredAction',
+     'TYPO3/CMS/Backend/Notification'
+   ], function(ImmediateAction, DeferredAction, Notification) {
+     const immediateActionCallback = new ImmediateAction(function () { /* your action code */ });
+     Notification.info(
+       'Great! We are almost done here...',
+       'Common default settings have been applied based on your previous input.',
+       0,
+       [
+         {label: 'Show settings', action: immediateActionCallback}
+       ]
+     );
+   });
+
+
+ImmediateAction
+---------------
+
+An action of type :js:`ImmediateAction` (:js:`TYPO3/CMS/Backend/ActionButtons/ImmediateAction`) is executed directly on
+click and closes the notification. This action type is suitable for e.g. linking to a backend module.
+
+The class accepts a callback method executing very simple logic.
+
+Example:
+
+.. code-block:: js
+
+   const immediateActionCallback = new ImmediateAction(function () {
+     require(['TYPO3/CMS/Backend/ModuleMenu'], function (ModuleMenu) {
+       ModuleMenu.App.showModule('web_layout');
+     });
+   });
+
+
+DeferredAction
+--------------
+
+An action of type :js:`DeferredAction` (:js:`TYPO3/CMS/Backend/ActionButtons/DeferredAction`) is recommended when a
+long-lasting task is executed, e.g. an AJAX request.
+
+This class accepts a callback method which must return either a resolved or rejected promise.
+
+The :js:`DeferredAction` replaces the action button with a spinner icon to indicate a task will take some time. It's
+still possible to dismiss a notification, which will **not** stop the execution.
+
+Example:
+
+.. code-block:: js
+
+   const deferredActionCallback = new DeferredAction(function () {
+     const myAction = async function() {
+       return await 'something';
+     }
+
+     return myAction();
+   });
+
+   const anotherDeferredActionCallback = new DeferredAction(function () {
+     // do some old-fashioned jQuery stuff
+     return Promise.resolve($.ajax(/* AJAX configuration */));
+   });
+
+
+.. index:: Backend, JavaScript, ext:backend