Commit f34013fa authored by Björn Jacob's avatar Björn Jacob Committed by waldhacker
Browse files

[DOCS] Update finisher documentation

The whole documentation about finishers has not
been touched since ages. A lot of information are
outdated. This patch fixes the mess.

Also improve a language label to clarify the usage of
the title field within the finishers "EmailToReceiver"
and "EmailToSender".

Resolves: #96048
Releases: main, 11.5
Change-Id: I3004194c37203993582e7f4687523ad766d3235d
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/74474

Tested-by: core-ci's avatarcore-ci <typo3@b13.com>
Tested-by: Mathias Brodala's avatarMathias Brodala <mbrodala@pagemachine.de>
Tested-by: waldhacker's avatarwaldhacker <hello@waldhacker.dev>
Reviewed-by: Mathias Brodala's avatarMathias Brodala <mbrodala@pagemachine.de>
Reviewed-by: waldhacker's avatarwaldhacker <hello@waldhacker.dev>
parent 197e763f
......@@ -50,9 +50,9 @@ closure
Confirmation finisher
---------------------
A simple finisher that outputs a given text.
A simple finisher that outputs a given text or a content element, respectively.
Usage within form definition
Usage within form definition for the case, you want to use a given text.
.. code-block:: yaml
......@@ -83,6 +83,37 @@ or create manually (not preferred)::
$formDefinition->addFinisher($confirmationFinisher);
Usage within form definition for the case, you want to output a content element.
.. code-block:: yaml
identifier: example-form
label: 'example'
type: Form
finishers:
-
identifier: Confirmation
options:
contentElement: 9
...
Usage through code::
$formDefinition->createFinisher('Confirmation', [
'contentElement' => 9,
]);
or create manually (not preferred)::
$confirmationFinisher = GeneralUtility::makeInstance(ConfirmationFinisher::class);
$confirmationFinisher->setOptions([
'contentElement' => 9,
]);
$formDefinition->addFinisher($confirmationFinisher);
.. _apireference-finisheroptions-confirmationfinisher-options:
Options
......@@ -112,7 +143,7 @@ This finisher remove the currently submited files.
Use this finisher e.g after the email finisher if you don't want to keep the files online.
Usage within form definition
Usage within form definition.
.. code-block:: yaml
......@@ -144,7 +175,7 @@ Email finisher
This finisher sends an email to one recipient.
EXT:form uses 2 EmailFinisher declarations with the identifiers ``EmailToReceiver`` and ``EmailToSender``.
Usage within form definition
Usage within form definition.
.. code-block:: yaml
......@@ -157,8 +188,9 @@ Usage within form definition
identifier: EmailToReceiver
options:
subject: 'Your message'
recipientAddress: your.company@example.com
recipientName: 'Your Company name'
recipients:
your.company@example.com: 'Your Company name'
ceo@example.com: 'CEO'
senderAddress: 'form@example.com'
senderName: 'form submitter'
...
......@@ -168,8 +200,10 @@ Usage through code::
$formDefinition->createFinisher('EmailToReceiver', [
'subject' => 'Your message',
'recipientAddress' => 'your.company@example.com',
'recipientName' => 'Your Company name',
'recipients' => [
'your.company@example.com' => 'Your Company name',
'ceo@example.com' => 'CEO'
],
'senderAddress' => 'form@example.com',
'senderName' => 'form submitter',
]);
......@@ -179,8 +213,10 @@ or create manually (not preferred)::
$emailFinisher = GeneralUtility::makeInstance(EmailFinisher::class);
$emailFinisher->setOptions([
'subject' => 'Your message',
'recipientAddress' => 'your.company@example.com',
'recipientName' => 'Your Company name',
'recipients' => [
'your.company@example.com' => 'Your Company name',
'ceo@example.com' => 'CEO'
],
'senderAddress' => 'form@example.com',
'senderName' => 'form submitter',
]);
......@@ -207,16 +243,16 @@ subject
undefined
:aspect:`Description`
Subject of the email
Subject of the email.
.. _apireference-finisheroptions-emailfinisher-options-recipientaddress:
.. _apireference-finisheroptions-emailfinisher-options-recipients:
recipientAddress
++++++++++++++++
recipients
++++++++++
:aspect:`Data type`
string
array
:aspect:`Mandatory`
Yes
......@@ -225,25 +261,7 @@ recipientAddress
undefined
:aspect:`Description`
Email address of the recipient (To)
.. _apireference-finisheroptions-emailfinisher-options-recipientname:
recipientName
+++++++++++++
:aspect:`Data type`
string
:aspect:`Mandatory`
No
:aspect:`Default value`
empty string
:aspect:`Description`
Human-readable name of the recipient
Email addresses and names of the recipients (To).
.. _apireference-finisheroptions-emailfinisher-options-senderaddress:
......@@ -261,7 +279,7 @@ senderAddress
undefined
:aspect:`Description`
Email address of the sender/ visitor (From)
Email address of the sender/ visitor (From).
.. _apireference-finisheroptions-emailfinisher-options-sendername:
......@@ -279,16 +297,16 @@ senderName
empty string
:aspect:`Description`
Human-readable name of the sender
Human-readable name of the sender.
.. _apireference-finisheroptions-emailfinisher-options-replytoaddress:
.. _apireference-finisheroptions-emailfinisher-options-replytorecipients:
replyToAddress
++++++++++++++
replyToRecipients
+++++++++++++++++
:aspect:`Data type`
string/ array
array
:aspect:`Mandatory`
No
......@@ -297,20 +315,16 @@ replyToAddress
undefined
:aspect:`Description`
Email address of to be used as reply-to email (use multiple addresses with an array)
Email addresses of to be used as reply-to emails.
.. note::
For the moment, the ``form editor`` cannot deal with multiple reply-to addresses (use multiple addresses with an array)
.. _apireference-finisheroptions-emailfinisher-options-carboncopyrecipients:
.. _apireference-finisheroptions-emailfinisher-options-carboncopyaddress:
carbonCopyAddress
+++++++++++++++++
carbonCopyRecipients
++++++++++++++++++++
:aspect:`Data type`
string/ array
array
:aspect:`Mandatory`
No
......@@ -319,20 +333,16 @@ carbonCopyAddress
undefined
:aspect:`Description`
Email address of the copy recipient (use multiple addresses with an array)
.. note::
Email addresses of the copy recipient.
For the moment, the ``form editor`` cannot deal with multiple copy recipient addresses (use multiple addresses with an array)
.. _apireference-finisheroptions-emailfinisher-options-blindcarbonCopyrecipients:
.. _apireference-finisheroptions-emailfinisher-options-blindcarboncopyaddress:
blindCarbonCopyAddress
++++++++++++++++++++++
blindCarbonCopyRecipients
+++++++++++++++++++++++++
:aspect:`Data type`
string/ array
array
:aspect:`Mandatory`
No
......@@ -341,32 +351,27 @@ blindCarbonCopyAddress
undefined
:aspect:`Description`
Email address of the blind copy recipient (use multiple addresses with an array)
Email address of the blind copy recipient.
.. note::
For the moment, the ``form editor`` cannot deal with multiple blind copy recipient addresses (use multiple addresses with an array)
.. _apireference-finisheroptions-emailfinisher-options-addhtmlpart:
.. _apireference-finisheroptions-emailfinisher-options-format:
format
++++++
addHtmlPart
+++++++++++
:aspect:`Data type`
string
bool
:aspect:`Mandatory`
No
:aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
html
:aspect:`possible values`
html/ plaintext
true
:aspect:`Description`
The format of the email. By default mails are sent as HTML.
If set, mails will contain a plaintext and HTML part, otherwise only a
plaintext part. That way, it can be used to disable HTML and enforce
plaintext-only mails.
.. _apireference-finisheroptions-emailfinisher-options-attachuploads:
......@@ -387,13 +392,13 @@ attachUploads
If set, all uploaded items are attached to the email.
.. _apireference-finisheroptions-emailfinisher-options-translation-translationfiles:
.. _apireference-finisheroptions-emailfinisher-options-translation-title:
translation.translationFiles
++++++++++++++++++++++++++++
title
+++++
:aspect:`Data type`
string/ array
string
:aspect:`Mandatory`
No
......@@ -402,9 +407,7 @@ translation.translationFiles
undefined
:aspect:`Description`
If set, this translation file(s) will be used for finisher option translations.
If not set, the translation file(s) from the 'Form' element will be used.
Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>` for more informations.
The title, being shown in the Email.
.. _apireference-finisheroptions-emailfinisher-options-translation-language:
......@@ -427,6 +430,26 @@ translation.language
Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>` for more informations.
.. _apireference-finisheroptions-emailfinisher-options-translation-translationfiles:
translation.translationFiles
++++++++++++++++++++++++++++
:aspect:`Data type`
array
:aspect:`Mandatory`
No
:aspect:`Default value (for 'EmailToReceiver' and 'EmailToSender' declarations)`
undefined
:aspect:`Description`
If set, this translation file(s) will be used for finisher option translations.
If not set, the translation file(s) from the 'Form' element will be used.
Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>` for more informations.
.. _apireference-finisheroptions-emailfinisher-options-layoutrootpaths:
layoutRootPaths
......@@ -508,7 +531,7 @@ FlashMessage finisher
A simple finisher that adds a message to the FlashMessageContainer.
Usage within form definition
Usage within form definition.
.. code-block:: yaml
......@@ -649,7 +672,7 @@ Redirect finisher
A simple finisher that redirects to another page.
Usage within form definition
Usage within form definition.
.. code-block:: yaml
......@@ -768,7 +791,7 @@ SaveToDatabase finisher
This finisher saves the data from a submitted form into a database table.
Usage within form definition
Usage within form definition.
.. code-block:: yaml
......@@ -850,7 +873,7 @@ or create manually (not preferred)::
You can write options as an array to perform multiple database operations.
Usage within form definition
Usage within form definition.
.. code-block:: yaml
......
......@@ -263,7 +263,9 @@ Implement a ``FormFactory`` and build the form::
$form->createFinisher('EmailToSender', [
'subject' => 'Hello',
'recipientAddress' => 'foo@example.com',
'recipients' => [
'your.company@example.com' => 'Your Company name'
],
'senderAddress' => 'bar@example.com',
]);
......@@ -1665,4 +1667,4 @@ Use the hook
*/
public function beforeRendering(\TYPO3\CMS\Form\Domain\Runtime\FormRuntime $formRuntime, \TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface $renderable)
{
}
\ No newline at end of file
}
......@@ -45,8 +45,9 @@ Example form definition
identifier: EmailToReceiver
options:
subject: 'Your message'
recipientAddress: 'your.company@example.com'
recipientName: 'Your company name'
recipients:
your.company@example.com: 'Your Company name'
ceo@example.com: 'CEO'
senderAddress: '{email}'
senderName: '{name}'
......
......@@ -482,17 +482,22 @@ you a ``form definition`` and the debug output of the corresponding
identifier: EmailToReceiver
options:
subject: 'Your message: {subject}'
recipientAddress: your.company@example.com
recipientName: 'Your Company name'
recipients:
your.company@example.com: 'Your Company name'
ceo@example.com: 'CEO'
senderAddress: '{email}'
senderName: '{name}'
replyToAddress: ''
carbonCopyAddress: ''
blindCarbonCopyAddress: ''
format: html
replyToRecipients:
replyTo.company@example.com: 'Your Company name'
carbonCopyRecipients:
cc.company@example.com: 'Your Company name'
blindCarbonCopyRecipients:
bcc.company@example.com: 'Your Company name'
addHtmlPart: true
attachUploads: 'true'
translation:
language: ''
title: ''
renderables:
-
identifier: page-1
......@@ -525,18 +530,27 @@ you a ``form definition`` and the debug output of the corresponding
"identifier": "EmailToReceiver",
"options": {
"subject": "Your message: {subject}",
"recipientAddress": "your.company@example.com",
"recipientName": "Your Company name",
"recipients": {
"your.company@example.com": "Your Company name",
"ceo@example.com": "CEO"
},
"senderAddress": "{email}",
"senderName": "{name}",
"replyToAddress": "",
"carbonCopyAddress": "",
"blindCarbonCopyAddress": "",
"format": "html",
"replyToRecipients": {
"replyTo.company@example.com": "Your Company name"
},
"carbonCopyRecipients": {
"cc.company@example.com": "Your Company name"
},
"blindCarbonCopyRecipients": {
"bcc.company@example.com": "Your Company name"
},
"addHtmlPart": true,
"attachUploads": true,
"translation": {
"language": ""
}
},
"title": ""
}
}
],
......
......@@ -54,7 +54,7 @@ by this.
elements:
senderAddress: ~
senderName: ~
replyToAddress: ~
replyToRecipients: ~
translation: ~
......
......@@ -496,7 +496,9 @@ The same mechanism (YAML, YAML + TypoScript) works for finisher options:
identifier: EmailToReceiver
options:
subject: My %s subject
recipientAddress: foo@example.org
recipients:
your.company@example.com: 'Your Company name'
ceo@example.com: 'CEO'
senderAddress: bar@example.org
translation:
translationFiles:
......
......@@ -400,15 +400,16 @@ the finisher is skipped.
identifier: EmailToReceiver
options:
subject: Yes, I am ready
recipientAddress: tritum@example.org
recipientName: TRITUM
recipients:
your.company@example.com: 'Your Company name'
senderAddress: tritum@example.org
senderName: tritum@example.org
-
identifier: EmailToSender
options:
subject: This is a copy of the form data
recipientAddress: '{email-address}'
recipients:
{email-address}: '{name}'
senderAddress: tritum@example.org
senderName: tritum@example.org
renderingOptions:
......
<
......@@ -74,16 +74,16 @@ options.subject
Subject of the email.
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.recipientaddress:
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.recipients:
options.recipientAddress
------------------------
options.recipients
------------------
:aspect:`Option path`
TYPO3.CMS.Form.prototypes.<prototypeIdentifier>.finishersDefinition.EmailToReceiver.options.recipientAddress
TYPO3.CMS.Form.prototypes.<prototypeIdentifier>.finishersDefinition.EmailToReceiver.options.recipients
:aspect:`Data type`
string
array
:aspect:`Needed by`
Frontend
......@@ -99,35 +99,7 @@ options.recipientAddress
- :ref:`"Accessing form runtime values"<concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`
:aspect:`Description`
Email address of the recipient (To).
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.recipientname:
options.recipientName
---------------------
:aspect:`Option path`
TYPO3.CMS.Form.prototypes.<prototypeIdentifier>.finishersDefinition.EmailToReceiver.options.recipientName
:aspect:`Data type`
string
:aspect:`Needed by`
Frontend
:aspect:`Mandatory`
No
:aspect:`Default value`
empty string
:aspect:`Good to know`
- :ref:`"Email finisher"<apireference-finisheroptions-emailfinisher>`
- :ref:`"Accessing form runtime values"<concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`
:aspect:`Description`
Human-readable name of the recipient.
Email addresses and names of the recipients (To).
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.senderaddress:
......@@ -186,16 +158,16 @@ options.senderName
Human-readable name of the sender.
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.replytoaddress:
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.replytorecipients:
options.replyToAddress
----------------------
options.replyToRecipients
-------------------------
:aspect:`Option path`
TYPO3.CMS.Form.prototypes.<prototypeIdentifier>.finishersDefinition.EmailToReceiver.options.replyToAddress
TYPO3.CMS.Form.prototypes.<prototypeIdentifier>.finishersDefinition.EmailToReceiver.options.replyToRecipients
:aspect:`Data type`
string/ array
array
:aspect:`Needed by`
Frontend
......@@ -211,23 +183,19 @@ options.replyToAddress
- :ref:`"Accessing form runtime values"<concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`
:aspect:`Description`
Email address of to be used as reply-to email (use multiple addresses with an array).
.. note::
Email addresses of to be used as reply-to emails.
For the moment, the ``form editor`` cannot deal with multiple reply-to addresses (use multiple addresses with an array)
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.carboncopyrecipients:
.. _typo3.cms.form.prototypes.<prototypeIdentifier>.finishersdefinition.emailtoreceiver.options.carboncopyaddress:
options.carbonCopyAddress
-------------------------
options.carbonCopyRecipients
----------------------------
:aspect:`Option path`
TYPO3.CMS.Form.prototypes.<prototypeIdentifier>.finishersDefinition.EmailToReceiver.options.carbonCopyAddress
TYPO3.CMS.Form.prototypes.<prototypeIdentifier>.finishersDefinition.EmailToReceiver.options.carbonCopyRecipients
:aspect:`Data type`
string/ array
array
:aspect:`Needed by`
Frontend
......@@ -243,23 +211,19 @@ options.carbonCopyAddress
- :ref:`"Accessing form runtime values"<concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`
:aspect:`Description`
Email address of the copy recipient (use multiple addresses with an array)
.. note::
For the moment, the ``form editor`` cannot deal with multiple copy recipient addresses (use multiple addresses with an array)
Email addresses of the copy recipient.