TYPO3 v15 dev-main snapshot ()
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-closurefinisher:
|
||||
|
||||
================
|
||||
Closure finisher
|
||||
================
|
||||
|
||||
The "Closure finisher" can only be used in programmatically-created forms. It allows
|
||||
you to execute your own finisher code without implementing/ declaring a finisher.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. include:: /Includes/_NoteFinisher.rst
|
||||
|
||||
.. _apireference-finisheroptions-closurefinisher-options:
|
||||
|
||||
Closure finisher option
|
||||
=======================
|
||||
|
||||
.. _apireference-finisheroptions-closurefinisher-options-closure:
|
||||
|
||||
.. confval:: closure
|
||||
:name: closurefinisher-closure
|
||||
:required: true
|
||||
:type: `?\Closure`
|
||||
:default: `null`
|
||||
|
||||
The name of the field as shown in the form.
|
||||
|
||||
.. _apireference-finisheroptions-closurefinisher:
|
||||
|
||||
Using the closure finisher programmatically
|
||||
===========================================
|
||||
|
||||
This finisher can only be used in programmatically-created forms. It allows
|
||||
you to execute your own finisher code without implementing/ declaring a finisher.
|
||||
|
||||
Code example:
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
|
||||
This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher`.
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
||||
use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
|
||||
class SomeClass
|
||||
{
|
||||
private function addClosureFinisher(FormDefinition $formDefinition)
|
||||
{
|
||||
|
||||
$closureFinisher = GeneralUtility::makeInstance(ClosureFinisher::class);
|
||||
$closureFinisher->setOption('closure', function ($finisherContext)
|
||||
{
|
||||
$formRuntime = $finisherContext->getFormRuntime();
|
||||
// ...
|
||||
});
|
||||
$formDefinition->addFinisher($closureFinisher);
|
||||
}
|
||||
}
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-confirmationfinisher:
|
||||
.. _finishers-confirmation-message:
|
||||
|
||||
=====================
|
||||
Confirmation finisher
|
||||
=====================
|
||||
|
||||
A basic finisher that outputs a text or content element.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. include:: /Includes/_NoteFinisher.rst
|
||||
|
||||
.. _apireference-finisheroptions-confirmationfinisher-options:
|
||||
|
||||
Confirmation finisher options
|
||||
=============================
|
||||
|
||||
This finisher outputs a text or a content element after the form has been submitted.
|
||||
|
||||
The settings of the finisher are:
|
||||
|
||||
.. _apireference-finisheroptions-confirmationfinisher-options-message:
|
||||
|
||||
.. confval:: message
|
||||
:name: confirmationfinisher-message
|
||||
:type: string
|
||||
:default: `The form has been submitted.`
|
||||
|
||||
Displays this text if the `contentElementUid` is not set.
|
||||
|
||||
.. confval:: contentElementUid
|
||||
:name: confirmationfinisher-contentElementUid
|
||||
:type: int
|
||||
:default: 0
|
||||
|
||||
Renders the content element with the supplied ID.
|
||||
|
||||
.. confval:: translation.propertiesExcludedFromTranslation
|
||||
:name: confirmationfinisher-translation-propertiesExcludedFromTranslation
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Defines a list of finisher option properties that should be excluded from
|
||||
translation.
|
||||
|
||||
When specified, the listed properties are not processed by the
|
||||
:php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation
|
||||
of finisher options. This prevents their values from being replaced by
|
||||
translated equivalents, even if translations exist for those options.
|
||||
|
||||
This option is usually generated automatically as soon as FlexForm overrides
|
||||
are in place and normally does not need to be set manually in the form
|
||||
definition.
|
||||
|
||||
See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
|
||||
for an example.
|
||||
|
||||
.. _concepts-finishers-confirmationfinisher-yaml:
|
||||
|
||||
Confirmation finisher in the YAML form definition
|
||||
=================================================
|
||||
|
||||
A basic finisher that outputs text or a content element.
|
||||
|
||||
Outputs text ``message``:
|
||||
|
||||
.. literalinclude:: _codesnippets/_form_with_confirmation_finisher.yaml
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
Outputs content element with id 42:
|
||||
|
||||
.. literalinclude:: _codesnippets/_form_with_confirmation_content_element.yaml
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _concepts-finishers-confirmationfinisher-yaml-propertiesExcludedFromTranslation:
|
||||
|
||||
Skip translation of overridden form finisher options
|
||||
====================================================
|
||||
|
||||
The following is an example of the `translation.propertiesExcludedFromTranslation <https://docs.typo3.org/permalink/typo3/cms-form:confval-confirmationfinisher-translation-propertiesexcludedfromtranslation>`_
|
||||
option being used to exclude three properties (subject, recipients and
|
||||
format) from translation.
|
||||
|
||||
Using this translation option, the properties can only be overridden by a FlexForm, not by the
|
||||
:php-short:`\TYPO3\CMS\Form\Service\TranslationService`.
|
||||
|
||||
This option is automatically generated as soon as FlexForm overrides are in place.
|
||||
|
||||
The following syntax is only documented for completeness. Nonetheless, it can
|
||||
also be added to a form definition YAML file.
|
||||
|
||||
.. literalinclude:: _codesnippets/_form_with_propertiesExcludedFromTranslation.yaml
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _apireference-finisheroptions-confirmationfinisher:
|
||||
|
||||
Using the confirmation finisher in PHP code
|
||||
===========================================
|
||||
|
||||
Developers can use the finisher key `Confirmation` to create
|
||||
confirmation finishers in their own classes:
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
|
||||
Th confirmation finisher is implemented in
|
||||
:php:`TYPO3\CMS\Form\Domain\Finishers\ConfirmationFinisher`.
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
|
||||
class SomeClass
|
||||
{
|
||||
private function addConfirmationnFinisherWithMessage(FormDefinition $formDefinition, string $message)
|
||||
{
|
||||
$formDefinition->createFinisher('Confirmation', [
|
||||
'message' => $message,
|
||||
]);
|
||||
}
|
||||
private function addConfirmationnFinisherWithContentElement(FormDefinition $formDefinition, int $contentElementUid)
|
||||
{
|
||||
$formDefinition->createFinisher('Confirmation', [
|
||||
'contentElementUid' => $contentElementUid,
|
||||
]);
|
||||
}
|
||||
}
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: Confirmation
|
||||
options:
|
||||
contentElementUid: 42
|
||||
#...
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: Confirmation
|
||||
options:
|
||||
message: 'Thx for using TYPO3'
|
||||
# ...
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
options:
|
||||
identifier: EmailToSender
|
||||
subject: 'Email to sender'
|
||||
recipients:
|
||||
recipient@example.org: 'Some Name'
|
||||
translation:
|
||||
propertiesExcludedFromTranslation:
|
||||
- subject
|
||||
- recipients
|
||||
- format
|
||||
# ...
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-deleteuploadsfinisher:
|
||||
.. _finishers-delete-uploads:
|
||||
|
||||
=======================
|
||||
DeleteUploads finishers
|
||||
=======================
|
||||
|
||||
The "DeleteUploads finisher" removes files that have been submitted. You can use this
|
||||
finisher after the email finisher if you do not want to keep the files
|
||||
in your TYPO3 installation.
|
||||
|
||||
.. note::
|
||||
|
||||
Finishers are only executed when a form is successfully submitted. If a user uploads
|
||||
a file but does not finish filling out the form, the uploaded files will not
|
||||
be deleted.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. include:: /Includes/_NoteFinisher.rst
|
||||
|
||||
.. _concepts-finishers-deleteuploadsfinisher-yaml:
|
||||
|
||||
DeleteUploads finisher in the YAML form definition
|
||||
==================================================
|
||||
|
||||
Use this finisher after the email finisher if you do not want to keep the files
|
||||
in your TYPO3 installation.
|
||||
|
||||
Finishers are executed in the order they are listed in the form definition
|
||||
YAML file:
|
||||
|
||||
.. literalinclude:: _codesnippets/_form.yaml
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _apireference-finisheroptions-deleteuploadsfinisher:
|
||||
|
||||
Using the DeleteUploads finisher in PHP code
|
||||
============================================
|
||||
|
||||
Developers can use the finisher key `DeleteUploads` to create
|
||||
deleteuploads finishers in their own classes:
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
|
||||
This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\DeleteUploadsFinisher`.
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
|
||||
class SomeClass
|
||||
{
|
||||
private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
|
||||
{
|
||||
$formDefinition->createFinisher('DeleteUploads');
|
||||
}
|
||||
}
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: EmailToSender
|
||||
options:
|
||||
subject: 'Your Message: {message}'
|
||||
-
|
||||
identifier: DeleteUploads
|
||||
# Define the delete uploads finisher AFTER the email finisher
|
||||
# ...
|
||||
@@ -0,0 +1,325 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-emailfinisher:
|
||||
|
||||
==============
|
||||
Email finisher
|
||||
==============
|
||||
|
||||
The EmailFinisher sends an email to one recipient. EXT:form has two
|
||||
EmailFinishers with the identifiers EmailToReceiver and EmailToSender.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. include:: /Includes/_NoteFinisher.rst
|
||||
|
||||
|
||||
.. _concepts-finishers-emailfinisher-backend:
|
||||
.. _finishers-email-to-sender:
|
||||
.. _finishers-email-to-receiver:
|
||||
|
||||
Using email finishers in the backend form editor
|
||||
================================================
|
||||
|
||||
Editors can use two email finishers in the backend form editor:
|
||||
|
||||
Email to sender (form submitter)
|
||||
This finisher sends an email with the contents of the form to the user
|
||||
submitting the form .
|
||||
|
||||
Email to receiver (you)
|
||||
This finisher sends an email with the contents of the form to the owner of the
|
||||
website. The settings of this finisher are the
|
||||
same as the "Email to sender" finisher
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options:
|
||||
|
||||
Options of the email finisher
|
||||
=============================
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-subject:
|
||||
|
||||
.. confval:: Subject [subject]
|
||||
:name: emailfinisher-subject
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
Subject of the email.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-recipients:
|
||||
|
||||
.. confval:: Recipients [recipients]
|
||||
:name: emailfinisher-recipients
|
||||
:type: array
|
||||
:required: true
|
||||
|
||||
Email addresses and names of the recipients (To).
|
||||
|
||||
**Email Address**
|
||||
Email address of a recipient, e.g. "some.recipient@example.com"
|
||||
or "{email-1}".
|
||||
**Name**
|
||||
Name of a recipient, e.g. "Some Recipient" or "{text-1}".
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-senderaddress:
|
||||
|
||||
.. confval:: Sender address [senderAddress]
|
||||
:name: emailfinisher-senderAddress
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
Email address of the sender, for example "your.company@example.org".
|
||||
|
||||
If `smtp <https://docs.typo3.org/permalink/t3coreapi:mail-configuration-smtp>`_
|
||||
is used, this email address needs to be allowed by the
|
||||
SMTP server. Use `replyToRecipients` if you want to enable the receiver to
|
||||
reply to the message.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-sendername:
|
||||
|
||||
.. confval:: Sender name [senderName]
|
||||
:name: emailfinisher-senderName
|
||||
:type: string
|
||||
:default: `''`
|
||||
|
||||
Name of the sender, for example "Your Company".
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-replytorecipients:
|
||||
|
||||
.. confval:: Reply-to Recipients [replyToRecipients]
|
||||
:name: emailfinisher-replyToRecipients
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Email address which will be used when someone replies to the email.
|
||||
|
||||
**Email Address**:
|
||||
Email address for reply-to.
|
||||
**Name**
|
||||
Name for reply-to.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-carboncopyrecipients:
|
||||
|
||||
.. confval:: CC Recipient [carbonCopyRecipients]
|
||||
:name: emailfinisher-carbonCopyRecipients
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Email address to which a copy of the email is sent. The information is
|
||||
visible to all other recipients.
|
||||
|
||||
**Email Address**:
|
||||
Email address for CC.
|
||||
**Name**
|
||||
Name for CC.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-blindcarboncopyrecipients:
|
||||
|
||||
.. confval:: BCC Recipients [blindCarbonCopyRecipients]
|
||||
:name: emailfinisher-blindCarbonCopyRecipients
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Email address to which a copy of the email is sent. The information is not
|
||||
visible to any of the recipients.
|
||||
|
||||
**Email Address**:
|
||||
Email address for BCC.
|
||||
**Name**
|
||||
Name for BCC.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-addhtmlpart:
|
||||
|
||||
.. confval:: Add HTML part [addHtmlPart]
|
||||
:name: emailfinisher-addHtmlPart
|
||||
:type: bool
|
||||
:default: `true`
|
||||
|
||||
If set, emails will contain plaintext and HTML, otherwise only plaintext.
|
||||
In this way, HTML can be disabled and plaintext-only emails enforced.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-attachuploads:
|
||||
|
||||
.. confval:: Attach uploads [attachUploads]
|
||||
:name: emailfinisher-attachUploads
|
||||
:type: bool
|
||||
:default: `true`
|
||||
|
||||
If set, all uploaded items are attached to the email.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-title:
|
||||
|
||||
.. confval:: Title [title]
|
||||
:name: emailfinisher-title
|
||||
:type: string
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
The title shown in the email.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-translation-language:
|
||||
|
||||
.. confval:: Translation language [translation.language]
|
||||
:name: emailfinisher-translation-language
|
||||
:type: string
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
If not set, the finisher options are translated depending on the current
|
||||
frontend language (if translations exist). This option allows you to force
|
||||
translations for a given language isocode, e.g. `da` or `de`.
|
||||
See :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>`.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-options:
|
||||
|
||||
Additional email finisher options
|
||||
=================================
|
||||
|
||||
Additional options can be set in the form definition YAML and
|
||||
programmatically in the options array but **not** in the backend editor:
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-translation-propertiesExcludedFromTranslation:
|
||||
|
||||
.. confval:: Properties excluded from translation [translation.propertiesExcludedFromTranslation]
|
||||
:name: emailfinisher-translation-propertiesExcludedFromTranslation
|
||||
:type: array
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
If not set, the finisher options are translated depending on the current frontend language (if translations exists).
|
||||
This option allows you to force translations for a given language isocode, e.g 'da' or 'de'.
|
||||
See :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>`.
|
||||
It will be skipped for all specified finisher options.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-translation-translationfiles:
|
||||
|
||||
.. confval:: translation.translationFiles
|
||||
:name: emailfinisher-translation-translationFiles
|
||||
:type: array
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
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>`.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-layoutrootpaths:
|
||||
|
||||
.. confval:: layoutRootPaths
|
||||
:name: emailfinisher-layoutRootPaths
|
||||
:type: array
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
Fluid layout paths.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-partialrootpaths:
|
||||
|
||||
.. confval:: partialRootPaths
|
||||
:name: emailfinisher-partialRootPaths
|
||||
:type: array
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
Fluid partial paths.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-templaterootpaths:
|
||||
|
||||
.. confval:: templateRootPaths
|
||||
:name: emailfinisher-templateRootPaths
|
||||
:type: array
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
Fluid template paths; all templates get the current :php:`FormRuntime`
|
||||
assigned as :code:`form` and the :php:`FinisherVariableProvider` assigned
|
||||
as :code:`finisherVariableProvider`.
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher-options-variables:
|
||||
|
||||
.. confval:: variables
|
||||
:name: emailfinisher-variables
|
||||
:type: array
|
||||
:required: false
|
||||
:default: `undefined`
|
||||
|
||||
Associative array of variables which are available inside the Fluid template.
|
||||
|
||||
.. _concepts-finishers-emailfinisher-yaml:
|
||||
|
||||
Email finishers in the YAML form definition
|
||||
===========================================
|
||||
|
||||
This finisher sends an email to one recipient.
|
||||
EXT:form has two email finishers with identifiers
|
||||
`EmailToReceiver` and `EmailToSender`.
|
||||
|
||||
.. literalinclude:: _codesnippets/_form.yaml
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _apireference-finisheroptions-emailfinisher:
|
||||
|
||||
Using Email finishers in PHP code
|
||||
=================================
|
||||
|
||||
Developers can create a confirmation finisher by using the key `EmailToReceiver`
|
||||
or `EmailToSender`.
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
|
||||
This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\EmailFinisher`.
|
||||
|
||||
.. _concepts-finishers-emailfinisher-bcc-recipients:
|
||||
|
||||
Working with BCC recipients
|
||||
===========================
|
||||
|
||||
Email finishers can work with different recipient types, including Carbon Copy
|
||||
(CC) and Blind Carbon Copy (BCC). Depending on the configuration of your server
|
||||
and TYPO3 instance, it may not be possible to send emails to BCC recipients.
|
||||
The :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_sendmail_command']`
|
||||
configuration value is important here. As documented in :ref:`CORE API <t3coreapi:mail-configuration-sendmail>`,
|
||||
TYPO3 recommends using the parameter :php:`-bs` (instead of :php:`-t -i`) with
|
||||
:php:`sendmail`. The parameter :php:`-bs` tells TYPO3 to use the SMTP standard
|
||||
so that BCC recipients are properly set. `Symfony <https://symfony.com/doc/current/mailer.html#using-built-in-transports>`__
|
||||
also mentions the :php:`-t` parameter problem. Since TYPO3 7.5
|
||||
(`#65791 <https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/7.5/Feature-65791-UsePHPConfiguredSendmailPathIfMAILtransportSendmailIsActive.html>`__)
|
||||
the :php:`transport_sendmail_command` is automatically set from the PHP runtime
|
||||
configuration and saved. If you have problems sending emails to BCC
|
||||
recipients, this could be the solution.
|
||||
|
||||
.. _concepts-finishers-emailfinisher-fluidemail:
|
||||
|
||||
About FluidEmail
|
||||
================
|
||||
|
||||
.. versionchanged:: 12.0
|
||||
The :php:`EmailFinisher` always sends email via :php:`FluidEmail`.
|
||||
|
||||
The FluidEmail finisher allows emails to be sent in a standardized way.
|
||||
|
||||
The finisher has an :yaml:`option` property :yaml:`title` that adds an email title to the default
|
||||
FluidEmail template. Variables can be used in options using the bracket syntax.
|
||||
These variables can be overwritten by FlexForm configuration in the form plugin
|
||||
|
||||
Use these options to customize the fluid templates:
|
||||
|
||||
* :yaml:`templateName`: The template name (for both HTML and plaintext, without the
|
||||
extension)
|
||||
* :yaml:`templateRootPaths`: The paths to the templates
|
||||
* :yaml:`partialRootPaths`: The paths to the partials
|
||||
* :yaml:`layoutRootPaths`: The paths to the layouts
|
||||
|
||||
.. note::
|
||||
The field :yaml:`templatePathAndFilename` is no longer evaluated.
|
||||
|
||||
Here is an example finisher configuration:
|
||||
|
||||
.. literalinclude:: _codesnippets/_example-email.yaml
|
||||
:caption: public/fileadmin/forms/my_form_with_email_finisher.yaml
|
||||
|
||||
These template files must exist:
|
||||
|
||||
* :file:`EXT:my_site_package/Resources/Private/Templates/Email/ContactForm.html`
|
||||
* :file:`EXT:my_site_package/Resources/Private/Templates/Email/ContactForm.txt`
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
identifier: contact
|
||||
type: Form
|
||||
prototypeName: standard
|
||||
finishers:
|
||||
-
|
||||
identifier: EmailToSender
|
||||
options:
|
||||
subject: 'Your Message: {message}'
|
||||
title: 'Hello {name}, your confirmation'
|
||||
templateName: ContactForm
|
||||
templateRootPaths:
|
||||
100: 'EXT:my_site_package/Resources/Private/Templates/Email/'
|
||||
partialRootPaths:
|
||||
100: 'EXT:my_site_package/Resources/Private/Partials/Email/'
|
||||
addHtmlPart: true
|
||||
+19
@@ -0,0 +1,19 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
|
||||
class SomeClass
|
||||
{
|
||||
private function addEmailToReceiverFinisher(FormDefinition $formDefinition)
|
||||
{
|
||||
$formDefinition->createFinisher('EmailToReceiver', [
|
||||
'subject' => 'Your message',
|
||||
'recipients' => [
|
||||
'your.company@example.com' => 'Your Company name',
|
||||
'ceo@example.com' => 'CEO'
|
||||
],
|
||||
'senderAddress' => $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress'],
|
||||
'senderName' => $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromName'],
|
||||
]);
|
||||
}
|
||||
}
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: EmailToReceiver
|
||||
options:
|
||||
subject: 'Your message'
|
||||
recipients:
|
||||
your.company@example.com: 'Your Company name'
|
||||
ceo@example.com: 'CEO'
|
||||
senderAddress: 'form@example.com'
|
||||
senderName: 'form submitter'
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-flashmessagefinisher:
|
||||
|
||||
=====================
|
||||
FlashMessage finisher
|
||||
=====================
|
||||
|
||||
The "FlashMessage finisher" is a basic finisher that adds a message to the
|
||||
FlashMessageContainer.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. note::
|
||||
|
||||
This finisher cannot be used in the backend form editor. It can only be used
|
||||
in a form definition YAML file or programmatically.
|
||||
|
||||
.. include:: /Includes/_NoteFinisher.rst
|
||||
|
||||
.. _apireference-finisheroptions-flashmessagefinisher-options:
|
||||
|
||||
FlashMessage finisher options
|
||||
=============================
|
||||
|
||||
The following options can be set (in the form definition YAML or
|
||||
programmatically):
|
||||
|
||||
.. _apireference-finisheroptions-flashmessagefinisher-options-messagebody:
|
||||
|
||||
.. confval:: messageBody
|
||||
:name: flashmessagefinisher-messageBody
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
The flash message. May contain placeholders like `%s` that
|
||||
are replaced with `messageArguments`.
|
||||
|
||||
.. _apireference-finisheroptions-flashmessagefinisher-options-messagetitle:
|
||||
|
||||
.. confval:: messageTitle
|
||||
:name: flashmessagefinisher-messageTitle
|
||||
:type: string
|
||||
:default: `''`
|
||||
|
||||
If set, is the flash message title.
|
||||
|
||||
.. _apireference-finisheroptions-flashmessagefinisher-options-messagearguments:
|
||||
|
||||
.. confval:: messageArguments
|
||||
:name: flashmessagefinisher-messageArguments
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
If `messageBody` contains placeholders (like `%s`), they will be replaced
|
||||
by these.
|
||||
|
||||
.. _apireference-finisheroptions-flashmessagefinisher-options-messagecode:
|
||||
|
||||
.. confval:: messageCode
|
||||
:name: flashmessagefinisher-messageCode
|
||||
:type: ?int
|
||||
:default: `null`
|
||||
|
||||
A unique code to identify the message. By convention, the
|
||||
unix time stamp at the time when the message is created is used,
|
||||
for example `1758455932`.
|
||||
|
||||
.. _apireference-finisheroptions-flashmessagefinisher-options-severity:
|
||||
|
||||
.. confval:: severity
|
||||
:name: flashmessagefinisher-severity
|
||||
:type: :php:`\TYPO3\CMS\Core\Type\ContextualFeedbackSeverity`
|
||||
:default: `ContextualFeedbackSeverity::OK`
|
||||
|
||||
The severity influences the display (color and icon) of the flash message.
|
||||
|
||||
.. confval:: translation.propertiesExcludedFromTranslation
|
||||
:name: flashmessagefinisher-translation-propertiesExcludedFromTranslation
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Defines a list of finisher option properties to be excluded from
|
||||
translation.
|
||||
|
||||
If set, these properties will not be processed by the
|
||||
:php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation
|
||||
of finisher options. This prevents their values from being replaced by
|
||||
translated equivalents, even if translations exist for those options.
|
||||
|
||||
This option is usually generated automatically as soon as FlexForm overrides
|
||||
are in place and normally does not need to be set manually in the form
|
||||
definition.
|
||||
|
||||
See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
|
||||
for an example.
|
||||
|
||||
.. _concepts-finishers-flashmessagefinisher-yaml:
|
||||
|
||||
FlashMessage finisher in a YAML form definition
|
||||
===============================================
|
||||
|
||||
.. literalinclude:: _codesnippets/_form.yaml
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _apireference-finisheroptions-flashmessagefinisher:
|
||||
|
||||
Using FlashMessage finishers in PHP code
|
||||
========================================
|
||||
|
||||
Developers can use the finisher key `FlashMessage` to create
|
||||
flash message finishers in their own classes:
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
|
||||
This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\FlashMessageFinisher`.
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
|
||||
class SomeClass
|
||||
{
|
||||
private function addFlashMessageFinisher(FormDefinition $formDefinition, string $message)
|
||||
{
|
||||
$formDefinition->createFinisher('FlashMessage', [
|
||||
'messageTitle' => 'Merci',
|
||||
'messageCode' => 201905041245,
|
||||
'messageBody' => 'Thx for using %s',
|
||||
'messageArguments' => ['TYPO3'],
|
||||
'severity' => ContextualFeedbackSeverity::OK,
|
||||
]);
|
||||
}
|
||||
}
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: FlashMessage
|
||||
options:
|
||||
messageTitle: 'Merci'
|
||||
messageCode: 201905041245
|
||||
messageBody: 'Thx for using %s'
|
||||
messageArguments:
|
||||
- 'TYPO3'
|
||||
severity: 0
|
||||
@@ -0,0 +1,62 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-ready-to-use:
|
||||
.. _apireference-finisheroptions:
|
||||
|
||||
======================
|
||||
Ready-to-use finishers
|
||||
======================
|
||||
|
||||
The TYPO3 Form Framework provides several built-in finishers that can be
|
||||
used out of the box. These handle common post submission tasks such as
|
||||
sending emails, showing confirmation messages, and saving data.
|
||||
|
||||
In addition, third-party extensions may provide further finishers, which
|
||||
can be found in the `TYPO3 Extension Repository (TER) <https://extensions.typo3.org/>`_.
|
||||
|
||||
.. card-grid::
|
||||
:columns: 1
|
||||
:columns-md: 2
|
||||
:gap: 4
|
||||
:class: pb-4
|
||||
:card-height: 100
|
||||
|
||||
.. card:: `Closure finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-closurefinisher>`_
|
||||
|
||||
Executes a custom PHP closure after a successful submission—use
|
||||
for ad-hoc logic without creating a full class.
|
||||
|
||||
.. card:: `Confirmation finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher>`_
|
||||
|
||||
Renders a confirmation/thank-you message (or view) once the form
|
||||
is submitted.
|
||||
|
||||
.. card:: `DeleteUploads finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-deleteuploadsfinisher>`_
|
||||
|
||||
Removes files uploaded during the submission—useful if after
|
||||
emailing them you don’t want to keep the files on the server.
|
||||
|
||||
.. card:: `Email finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-emailfinisher>`_
|
||||
|
||||
Sends an email with the submitted data; supports Fluid
|
||||
templates and placeholders for field values.
|
||||
|
||||
.. card:: :doc:`Flash message finisher <FlashMessageFinisher/Index>`
|
||||
|
||||
Shows a flash message to the user after submit (e.g., success or
|
||||
info notice).
|
||||
|
||||
.. card:: `Redirect finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-redirectfinisher>`_
|
||||
|
||||
Redirects to another page or route after submit; must be last
|
||||
finisher since it stops subsequent finishers.
|
||||
|
||||
.. card:: `SaveToDatabase finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-savetodatabasefinisher>`_
|
||||
|
||||
Persists submitted form values to a database table according to
|
||||
your mapping/configuration.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:glob:
|
||||
|
||||
*/Index
|
||||
@@ -0,0 +1,135 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-redirectfinisher:
|
||||
.. _finishers-redirect:
|
||||
|
||||
=================
|
||||
Redirect finisher
|
||||
=================
|
||||
|
||||
This finisher redirects the user to a particular page after the form has been submitted.
|
||||
Parameters can be added to the URL.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. important::
|
||||
|
||||
Finishers are executed in the order defined in your form definition.
|
||||
This finisher stops the execution of all subsequent finishers in order to perform
|
||||
the redirect. Therefore, this finisher should always be the last finisher to be
|
||||
executed. Finishers placed after this one in the form definition will be ignored.
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher-options:
|
||||
|
||||
Redirect finisher options
|
||||
=========================
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher-options-pageuid:
|
||||
|
||||
.. confval:: Page: [pageUid]
|
||||
:name: redirectfinisher-pageUid
|
||||
:type: int
|
||||
:required: true
|
||||
:default: `1`
|
||||
|
||||
ID of the page to redirect to. Button :guilabel:`Page` can be used to select
|
||||
a page from the page tree.
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher-options-additionalparameters:
|
||||
|
||||
.. confval:: Additional parameters: [additionalParameters]
|
||||
:name: redirectfinisher-additionalParameters
|
||||
:type: string
|
||||
:required: false
|
||||
:default: `''`
|
||||
|
||||
URL parameters which will be appended to the URL.
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher-options-fragment:
|
||||
|
||||
.. confval:: URL fragment: [fragment]
|
||||
:name: redirectfinisher-fragment
|
||||
:type: string
|
||||
:required: false
|
||||
:default: `''`
|
||||
|
||||
ID of a content element identifier or a custom fragment
|
||||
identifier. This will be appended to the URL and used as section anchor.
|
||||
|
||||
Adds a fragment (e.g. :html:`#c9` or :html:`#foo`) to the redirect link.
|
||||
The :html:`#` character can be omitted.
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher-options-additional:
|
||||
|
||||
Additional redirect finisher options
|
||||
====================================
|
||||
|
||||
These options can be set in the form definition YAML or
|
||||
programmatically in the options array. They cannot be set in the backend form editor:
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher-options-delay:
|
||||
|
||||
.. confval:: delay
|
||||
:name: redirectfinisher-delay
|
||||
:type: int
|
||||
:required: false
|
||||
:default: `0`
|
||||
|
||||
The redirect delay in seconds.
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher-options-statuscode:
|
||||
|
||||
.. confval:: statusCode
|
||||
:name: redirectfinisher-statusCode
|
||||
:type: int
|
||||
:required: false
|
||||
:default: `303`
|
||||
|
||||
The HTTP status code for the redirect. Default is "303 See Other".
|
||||
|
||||
.. confval:: translation.propertiesExcludedFromTranslation
|
||||
:name: redirectfinisher-translation-propertiesExcludedFromTranslation
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Defines a list of finisher option properties to be excluded from
|
||||
translation.
|
||||
|
||||
If set, these properties are not processed by the
|
||||
:php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation.
|
||||
This prevents their values from being replaced by
|
||||
translated equivalents, even if translations exist for those options.
|
||||
|
||||
This option is usually generated automatically shen FlexForm overrides
|
||||
are in place and normally does not need to be set manually in the form
|
||||
definition.
|
||||
|
||||
See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
|
||||
for an example.
|
||||
|
||||
.. _concepts-finishers-redirectfinisher-yaml:
|
||||
|
||||
Redirect finisher in a YAML form definition
|
||||
===========================================
|
||||
|
||||
.. literalinclude:: _codesnippets/_form.yaml
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _concepts-finishers-redirectfinisher-last:
|
||||
|
||||
Example: Load the redirect finisher last
|
||||
========================================
|
||||
|
||||
.. literalinclude:: _codesnippets/_example-redirect.yaml
|
||||
:caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
|
||||
|
||||
.. _apireference-finisheroptions-redirectfinisher:
|
||||
|
||||
Using a Redirect finisher in PHP code
|
||||
=====================================
|
||||
|
||||
Developers can use the finisher key `Redirect` to create redirect finishers in their own classes:
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
|
||||
This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\RedirectFinisher`.
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
identifier: contact
|
||||
type: Form
|
||||
prototypeName: standard
|
||||
finishers:
|
||||
-
|
||||
identifier: EmailToSender
|
||||
options:
|
||||
subject: 'Your Message: {message}'
|
||||
## ...
|
||||
-
|
||||
identifier: DeleteUploads
|
||||
-
|
||||
# Attention! The Redirect finisher stops the execution of all finishers
|
||||
identifier: Redirect
|
||||
options:
|
||||
pageUid: 1
|
||||
additionalParameters: 'param1=value1¶m2=value2'
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
|
||||
class SomeClass
|
||||
{
|
||||
private function addRedirectFinisher(FormDefinition $formDefinition)
|
||||
{
|
||||
$formDefinition->createFinisher('Redirect', [
|
||||
'pageUid' => 1,
|
||||
'additionalParameters' => 'param1=value1¶m2=value2',
|
||||
]);
|
||||
}
|
||||
}
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: Redirect
|
||||
options:
|
||||
pageUid: 1
|
||||
additionalParameters: 'param1=value1¶m2=value2'
|
||||
+245
@@ -0,0 +1,245 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-savetodatabasefinisher:
|
||||
|
||||
=======================
|
||||
SaveToDatabase finisher
|
||||
=======================
|
||||
|
||||
The "SaveToDatabase finisher" saves data from a submitted form into a
|
||||
database table.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. note::
|
||||
|
||||
This finisher cannot be used in the backend form editor. It can only be
|
||||
used in a form definition YAML file or programmatically.
|
||||
|
||||
.. include:: /Includes/_NoteFinisher.rst
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options:
|
||||
|
||||
SaveToDatabase finisher options
|
||||
===============================
|
||||
|
||||
The finisher options can be set in the form definition YAML file or
|
||||
programmatically:
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-table:
|
||||
|
||||
.. confval:: table
|
||||
:name: savetodatabasefinisher-table
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
Insert or update values in this table.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-mode:
|
||||
|
||||
.. confval:: mode
|
||||
:name: savetodatabasefinisher-mode
|
||||
:type: string
|
||||
:default: `'insert'`
|
||||
|
||||
`insert`
|
||||
will create a new database row with the values from the submitted form
|
||||
and/or some predefined values. See also :confval:`savetodatabasefinisher-elements` and
|
||||
:confval:`savetodatabasefinisher-databaseColumnMappings`.
|
||||
|
||||
`update`
|
||||
will update a database row with the values from the submitted form
|
||||
and/or some predefined values. In this case :confval:`savetodatabasefinisher-whereClause` is required.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-whereclause:
|
||||
|
||||
.. confval:: whereClause
|
||||
:name: savetodatabasefinisher-whereClause
|
||||
:type: array
|
||||
:required: true (if mode = update)
|
||||
:default: `[]`
|
||||
|
||||
The ``where`` clause for a database update action.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements:
|
||||
|
||||
.. confval:: elements
|
||||
:name: savetodatabasefinisher-elements
|
||||
:type: array
|
||||
:required: true
|
||||
|
||||
Use `options.elements` to map form element values to database columns (they must exist).
|
||||
Each key in `options.elements` has to match a form element identifier.
|
||||
The value of each key in `options.elements` is an array containing additional information.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-mapondatabasecolumn:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.mapOnDatabaseColumn
|
||||
:name: savetodatabasefinisher-elements-mapOnDatabaseColumn
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
The value from the submitted form element with the identifier
|
||||
`<formElementIdentifier>` will be written into this database column.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-skipifvalueisempty:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.skipIfValueIsEmpty
|
||||
:name: savetodatabasefinisher-elements-skipIfValueIsEmpty
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
Set this to true if the database column should not be written if the value from the
|
||||
submitted form element with the identifier `<formElementIdentifier>` is empty
|
||||
(e.g. for password fields). Empty means strings without content, whitespace is valid content.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-hashed:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.hashed
|
||||
:name: savetodatabasefinisher-elements-hashed
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
Set this to true if the value from the submitted form element should be hashed before
|
||||
writing into the database.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-savefileidentifierinsteadofuid:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.saveFileIdentifierInsteadOfUid
|
||||
:name: savetodatabasefinisher-elements-saveFileIdentifierInsteadOfUid
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
By default, the uid of the FAL object will be written into the database column.
|
||||
Set this to true if you want to store the FAL identifier
|
||||
(e.g. `1:/user_uploads/some_uploaded_pic.jpg`) instead.
|
||||
|
||||
This only applies for form elements which create a FAL object like
|
||||
`FileUpload` or `ImageUpload`.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-dateformat:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.dateFormat
|
||||
:name: savetodatabasefinisher-elements-dateFormat
|
||||
:type: string
|
||||
:default: `'U'`
|
||||
|
||||
If the internal datatype is :php:`\DateTime` (true for the form element type
|
||||
:yaml:`Date`), the object needs to be converted into a string.
|
||||
This option defines the format of the date. You can use any format accepted by
|
||||
the PHP :php:`date()` function.
|
||||
Default is `'U'` (Unix timestamp).
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings:
|
||||
|
||||
.. confval:: databaseColumnMappings
|
||||
:name: savetodatabasefinisher-databaseColumnMappings
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Use this to map database columns to values.
|
||||
Each key within `options.databaseColumnMappings` has to match an existing database column.
|
||||
Each value in `options.databaseColumnMappings` is an array with
|
||||
additional information.
|
||||
|
||||
This mapping is done *before* :confval:`savetodatabasefinisher-elements` are mapped.
|
||||
If you map both, the value from :confval:`savetodatabasefinisher-elements` will override the
|
||||
:confval:`savetodatabasefinisher-databaseColumnMappings-value`.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings-value:
|
||||
|
||||
.. confval:: databaseColumnMappings.<databaseColumnName>.value
|
||||
:name: savetodatabasefinisher-databaseColumnMappings-value
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
The value which will be written to the database column.
|
||||
You can also use the :ref:`FormRuntime accessor feature
|
||||
<concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`
|
||||
to access properties from the `FormRuntime`, e.g. `{<formElementIdentifier>}`.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings-skipifvalueisempty:
|
||||
|
||||
.. confval:: databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty
|
||||
:name: savetodatabasefinisher-databaseColumnMappings-skipIfValueIsEmpty
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
Set this to true if the database column should not be written if the value from
|
||||
:confval:`savetodatabasefinisher-databaseColumnMappings-value` is empty.
|
||||
|
||||
.. confval:: translation.propertiesExcludedFromTranslation
|
||||
:name: savetodatabasefinisher-translation-propertiesExcludedFromTranslation
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Defines a list of finisher option properties to be excluded from
|
||||
translation.
|
||||
|
||||
If set, these properties are not processed by the
|
||||
:php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation.
|
||||
This prevents the values from being replaced by
|
||||
translated equivalents, even if translations exist for those options.
|
||||
|
||||
This option is usually generated when FlexForm overrides
|
||||
exist and normally does not need to be set manually in the form
|
||||
definition.
|
||||
|
||||
See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
|
||||
for an example.
|
||||
|
||||
.. _concepts-finishers-savetodatabasefinisher-yaml:
|
||||
|
||||
SaveToDatabase finisher in a YAML form definition
|
||||
=================================================
|
||||
|
||||
This finisher saves data from a submitted form into a database table.
|
||||
|
||||
.. literalinclude:: _codesnippets/_form.yaml
|
||||
:linenos:
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _concepts-finishers-savetodatabasefinisher-example-news:
|
||||
|
||||
Example: adding uploads to ext:news (fal_related_files and fal_media):
|
||||
======================================================================
|
||||
|
||||
.. literalinclude:: _codesnippets/_example-fal-uploads_news.yaml
|
||||
:linenos:
|
||||
:caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher:
|
||||
|
||||
Using a SaveToDatabase finisher in PHP code
|
||||
================================================
|
||||
|
||||
Developers can use the finisher key `SaveToDatabase` to create
|
||||
flash message finishers in their own classes:
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
:linenos:
|
||||
|
||||
This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\SaveToDatabaseFinisher`.
|
||||
|
||||
.. _concepts-finishers-savetodatabasefinisher-multiple:
|
||||
|
||||
Multiple database operations
|
||||
============================
|
||||
|
||||
You can use options to perform multiple database operations.
|
||||
|
||||
Example form definition file (performs inserts):
|
||||
|
||||
.. literalinclude:: _codesnippets/_example-fal-uploads_news.yaml
|
||||
:linenos:
|
||||
:caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
|
||||
|
||||
Using PHP code (performs an update):
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
:linenos:
|
||||
|
||||
You can access inserted UIDs with '{SaveToDatabase.insertedUids.<theArrayKeyNumberInsideOptions>}'.
|
||||
If you perform an insert operation, the inserted values will be stored in the FinisherVariableProvider.
|
||||
<theArrayKeyNumberInOptions> references the numeric options.* key.
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
-
|
||||
identifier: SaveToDatabase
|
||||
options:
|
||||
-
|
||||
table: tx_news_domain_model_news
|
||||
mode: insert
|
||||
elements:
|
||||
my-field:
|
||||
mapOnDatabaseColumn: bodytext
|
||||
imageupload-1:
|
||||
mapOnDatabaseColumn: fal_media
|
||||
fileupload-1:
|
||||
mapOnDatabaseColumn: fal_related_files
|
||||
databaseColumnMappings:
|
||||
pid:
|
||||
value: 3
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
datetime:
|
||||
value: '{__currentTimestamp}'
|
||||
crdate:
|
||||
value: '{__currentTimestamp}'
|
||||
hidden:
|
||||
value: 1
|
||||
-
|
||||
table: sys_file_reference
|
||||
mode: insert
|
||||
elements:
|
||||
imageupload-1:
|
||||
mapOnDatabaseColumn: uid_local
|
||||
skipIfValueIsEmpty: true
|
||||
databaseColumnMappings:
|
||||
tablenames:
|
||||
value: tx_news_domain_model_news
|
||||
fieldname:
|
||||
value: fal_media
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
crdate:
|
||||
value: '{__currentTimestamp}'
|
||||
showinpreview:
|
||||
value: 1
|
||||
uid_foreign:
|
||||
value: '{SaveToDatabase.insertedUids.0}'
|
||||
-
|
||||
table: sys_file_reference
|
||||
mode: insert
|
||||
elements:
|
||||
fileupload-1:
|
||||
mapOnDatabaseColumn: uid_local
|
||||
skipIfValueIsEmpty: true
|
||||
databaseColumnMappings:
|
||||
tablenames:
|
||||
value: tx_news_domain_model_news
|
||||
fieldname:
|
||||
value: fal_related_files
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
crdate:
|
||||
value: '{__currentTimestamp}'
|
||||
uid_foreign:
|
||||
value: '{SaveToDatabase.insertedUids.0}'
|
||||
-
|
||||
table: sys_file_reference
|
||||
mode: update
|
||||
whereClause:
|
||||
uid_foreign: '{SaveToDatabase.insertedUids.0}'
|
||||
uid_local: 0
|
||||
databaseColumnMappings:
|
||||
pid:
|
||||
value: 0
|
||||
uid_foreign:
|
||||
value: 0
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
||||
use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
class SomeClass
|
||||
{
|
||||
private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
|
||||
{
|
||||
$formDefinition->createFinisher('SaveToDatabase', [
|
||||
1 => [
|
||||
'table' => 'my_table',
|
||||
'mode' => 'insert',
|
||||
'databaseColumnMappings' => [
|
||||
'some_column' => ['value' => 'cool'],
|
||||
],
|
||||
],
|
||||
2 => [
|
||||
'table' => 'my_other_table',
|
||||
'mode' => 'update',
|
||||
'whereClause' => [
|
||||
'pid' => 1,
|
||||
],
|
||||
'databaseColumnMappings' => [
|
||||
'some_other_column' => ['value' => '{SaveToDatabase.insertedUids.1}'],
|
||||
],
|
||||
],
|
||||
]);
|
||||
}
|
||||
}
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
||||
use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
class SomeClass
|
||||
{
|
||||
private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
|
||||
{
|
||||
$formDefinition->createFinisher('SaveToDatabase', [
|
||||
'table' => 'fe_users',
|
||||
'mode' => 'update',
|
||||
'whereClause' => [
|
||||
'uid' => 1,
|
||||
],
|
||||
'databaseColumnMappings' => [
|
||||
'pid' => ['value' => 1],
|
||||
],
|
||||
'elements' => [
|
||||
'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
|
||||
'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
|
||||
'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
|
||||
'advancedpassword-1' => [
|
||||
'mapOnDatabaseColumn' => 'password',
|
||||
'skipIfValueIsEmpty' => true,
|
||||
'hashed' => true
|
||||
],
|
||||
],
|
||||
]);
|
||||
}
|
||||
}
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: SaveToDatabase
|
||||
options:
|
||||
1:
|
||||
table: 'my_table'
|
||||
mode: insert
|
||||
databaseColumnMappings:
|
||||
some_column:
|
||||
value: 'cool'
|
||||
2:
|
||||
table: 'my_other_table'
|
||||
mode: update
|
||||
whereClause:
|
||||
pid: 1
|
||||
databaseColumnMappings:
|
||||
some_other_column:
|
||||
value: '{SaveToDatabase.insertedUids.1}'
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: SaveToDatabase
|
||||
options:
|
||||
table: 'fe_users'
|
||||
mode: update
|
||||
whereClause:
|
||||
uid: 1
|
||||
databaseColumnMappings:
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
pid:
|
||||
value: 1
|
||||
elements:
|
||||
textfield-identifier-1:
|
||||
mapOnDatabaseColumn: 'first_name'
|
||||
textfield-identifier-2:
|
||||
mapOnDatabaseColumn: 'last_name'
|
||||
textfield-identifier-3:
|
||||
mapOnDatabaseColumn: 'username'
|
||||
advancedpassword-1:
|
||||
mapOnDatabaseColumn: 'password'
|
||||
skipIfValueIsEmpty: true
|
||||
hashed: true
|
||||
Reference in New Issue
Block a user