TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,99 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-77268:
+
+==========================================================
+Feature: #77268 - Introduce JavaScript trigger request API
+==========================================================
+
+See :issue:`77268`
+
+Description
+===========
+
+JavaScript event handling the backend of the TYPO3 core is based on the optimistic
+assumption, that most executions can be executed sequentially and are processed
+just in time. This concept does not consider the fact that other nested components
+can defer the execution based on additional user input e.g. as used in confirmation
+dialogs.
+
+That's why a trigger request API is introduced to first inform dependent components
+about a planned action which will defer the regular execution based on specific
+application state logic of registered components. In the current implementation,
+FormEngine's edit forms register themselves to be notified, thus accidentally
+closing modified forms by clicking e.g. the module menu any other page in the
+page tree can be handled.
+
+Registering component
+~~~~~~~~~~~~~~~~~~~~~
+
+The following code attaches or detaches a particular component (a **consumer**)
+to be notified.
+
+.. code-block:: javascript
+
+	// FormEngine must implement the Consumable interface,
+        // thus having a function named consume(interactionRequest)
+	top.TYPO3.Backend.consumerScope.attach(FormEngine);
+	top.TYPO3.Backend.consumerScope.detach(FormEngine);
+
+Invoking consumers
+~~~~~~~~~~~~~~~~~~
+
+Registered consumers are invoked with a specific interaction request that has a
+defined action type and optionally additional information about the parent call
+(e.g. some client event issued by users). Invocations return a jQuery.Deferred()
+object that resolves when no consumers are registered or every consumer sends a
+resolve command as well - if only one consumer rejects, the collective invocation
+promise is rejected as well.
+
+.. code-block:: javascript
+
+	var deferred = TYPO3.Backend.consumerScope.invoke(
+		new TriggerRequest('typo3.setUrl', interactionRequest)
+	);
+	deferred
+		.then(function() { console.log('consumers are resolved'); })
+		.fail(function() { console.log('some consumer was rejected'); });
+
+Creating interaction requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Currently there are two types of requests, `ClientRequest` that is based on some
+client event (e.g. `click` event) and `TriggerRequest` which may be based on some
+parent request of type `InteractionRequest` - this is used to cascade actions.
+
+.. code-block:: javascript
+
+   var clickRequest = new ClientRequest('typo3.showModule', event);
+   var triggerRequestA = new TriggerRequest('typo3.a', clickRequest);
+   var triggerRequestB = new TriggerRequest('typo3.b', triggerRequestA);
+
+In the example `triggerRequestB` has all information from the initial click
+event down to the specific `typo3.b` action type. The first request can be
+resolved from the most specific request by `triggerRequestB.outerMostRequest`
+and will return `clickRequest` in this case.
+
+Working with interaction requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ `triggerRequestB.concerns(clickRequest)` checks whether `clickRequest` is an
+  ancestor request in the cascade of `triggerRequestB` (which is true, based on
+  the previous example)
+ `triggerRequestB.concernsType('typo3.showModule')` checks whether `typo3.showModule`
+  is the type of some ancestor request in the cascade of `triggerRequestB` (which
+  is true, based on the previous example)
+ `triggerRequestB.outerMostRequest.setProcessedData({response: true})` sets the
+  property evaluated by `clickRequest.isProcessed()` to `true` and stores any
+  custom user response (e.g. from some confirmation dialog) at the outer-most
+  interaction request
+
+Impact
+======
+
+Using interaction requests requires some modifications in the JavaScript processing
+logic which changes from sequential processing to possibly deferred asynchronous
+processing. This is required since e.g. user input is required first to be able
+to continue the processing. The created promises are based on `jQuery.Deferred`.
+
+.. index:: Backend, JavaScript