Finisher Options

Closure finisher

This finisher can only be used in programmatically-created forms. It makes it possible to execute one’s own finisher code without having to implement/ declare this finisher.

Usage through code:

$closureFinisher = GeneralUtility::makeInstance(ClosureFinisher::class);
$closureFinisher->setOption('closure', function($finisherContext) {
    $formRuntime = $finisherContext->getFormRuntime();
    // ...
});
$formDefinition->addFinisher($closureFinisher);

Options

closure

Data type
Closure
Mandatory
Yes
Default value
null

Confirmation finisher

A simple finisher that outputs a given text or a content element, respectively.

Usage within form definition for the case, you want to use a given text.

identifier: example-form
label: 'example'
type: Form

finishers:
  -
    identifier: Confirmation
    options:
      message: 'Thx for using TYPO3'
...

Usage through code:

$formDefinition->createFinisher('Confirmation', [
    'message' => 'foo',
]);

or create manually (not preferred):

$confirmationFinisher = GeneralUtility::makeInstance(ConfirmationFinisher::class);
$confirmationFinisher->setOptions([
    'message' => 'foo',
]);
$formDefinition->addFinisher($confirmationFinisher);

Usage within form definition for the case, you want to output a content element.

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);

Options

message

Data type
string
Mandatory
Yes
Default value
The form has been submitted.

DeleteUploads finisher

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.

identifier: example-form
label: 'example'
type: Form

finishers:
  -
    identifier: DeleteUploads
...

Usage through code:

$formDefinition->createFinisher('DeleteUploads');

or create manually (not preferred):

$deleteUploadsFinisher = GeneralUtility::makeInstance(DeleteUploadsFinisher::class);
$formDefinition->addFinisher($deleteUploadsFinisher);

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.

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'
...

Usage through code:

$formDefinition->createFinisher('EmailToReceiver', [
    'subject' => 'Your message',
    'recipients' => [
        'your.company@example.com' => 'Your Company name',
        'ceo@example.com' => 'CEO'
    ],
    'senderAddress' => 'form@example.com',
    'senderName' => 'form submitter',
]);

or create manually (not preferred):

$emailFinisher = GeneralUtility::makeInstance(EmailFinisher::class);
$emailFinisher->setOptions([
    'subject' => 'Your message',
    'recipients' => [
        'your.company@example.com' => 'Your Company name',
        'ceo@example.com' => 'CEO'
    ],
    'senderAddress' => 'form@example.com',
    'senderName' => 'form submitter',
]);
$formDefinition->addFinisher($emailFinisher);

Options

subject

Data type
string
Mandatory
Yes
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Subject of the email.

recipients

Data type
array
Mandatory
Yes
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Email addresses and names of the recipients (To).

senderAddress

Data type
string
Mandatory
Yes
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Email address of the sender/ visitor (From).

senderName

Data type
string
Mandatory
No
Default value
empty string
Description
Human-readable name of the sender.

replyToRecipients

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Email addresses of to be used as reply-to emails.

carbonCopyRecipients

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Email addresses of the copy recipient.

blindCarbonCopyRecipients

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Email address of the blind copy recipient.

addHtmlPart

Data type
bool
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
true
Description
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.

attachUploads

Data type
bool
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
true
Description
If set, all uploaded items are attached to the email.

title

Data type
string
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
The title, being shown in the Email.

translation.language

Data type
string
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
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 ‘dk’ or ‘de’. Read Translate finisher options for more informations.

translation.translationFiles

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
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 Translate finisher options for more informations.

layoutRootPaths

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Fluid layout paths

partialRootPaths

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Fluid partial paths

templateRootPaths

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
Fluid template paths; all templates get the current FormRuntime assigned as form and the FinisherVariableProvider assigned as finisherVariableProvider.

variables

Data type
array
Mandatory
No
Default value (for ‘EmailToReceiver’ and ‘EmailToSender’ declarations)
undefined
Description
associative array of variables which are available inside the Fluid template

FlashMessage finisher

A simple finisher that adds a message to the FlashMessageContainer.

Usage within form definition.

identifier: example-form
label: 'example'
type: Form

finishers:
  -
    identifier: FlashMessage
    options:
      messageTitle: 'Merci'
      messageCode: 201905041245
      messageBody: 'Thx for using %s'
      messageArguments:
        - 'TYPO3'
      severity: 0
...

Usage through code:

$formDefinition->createFinisher('FlashMessage', [
    'messageTitle' => 'Merci',
    'messageCode' => 201905041245,
    'messageBody' => 'Thx for using %s',
    'messageArguments' => ['TYPO3'],
    'severity' => \TYPO3\CMS\Core\Messaging\AbstractMessage::OK,
]);

or create manually (not preferred):

$flashMessageFinisher = GeneralUtility::makeInstance(FlashMessageFinisher::class);
$flashMessageFinisher->setOptions([
    'messageTitle' => 'Merci',
    'messageCode' => 201905041245,
    'messageBody' => 'Thx for using %s',
    'messageArguments' => ['TYPO3'],
    'severity' => \TYPO3\CMS\Core\Messaging\AbstractMessage::OK,
]);
$formDefinition->addFinisher($flashMessageFinisher);

Options

messageBody

Data type
string
Mandatory
Yes
Description
The flash message body

messageTitle

Data type
string
Mandatory
No
Default value
empty string
Description
The flash message title, if needed

messageArguments

Data type
array
Mandatory
No
Default value
empty array
Description
The flash message arguments, if needed

messageCode

Data type
int
Mandatory
Yes
Description
The flash message code

severity

Data type
int
Mandatory
No
Default value
TYPO3CMSCoreMessagingAbstractMessage::OK (0)
Description
The flash message severity code. See TYPO3CMSCoreMessagingAbstractMessage constants for the codes.

Redirect finisher

A simple finisher that redirects to another page.

Usage within form definition.

identifier: example-form
label: 'example'
type: Form

finishers:
  -
    identifier: Redirect
    options:
      pageUid: 1
      additionalParameters: 'param1=value1&param2=value2'
...

Usage through code:

$formDefinition->createFinisher('Redirect', [
    'pageUid' => 1,
    'additionalParameters' => 'param1=value1&param2=value2',
]);

or create manually (not preferred):

$redirectFinisher = GeneralUtility::makeInstance(RedirectFinisher::class);
$redirectFinisher->setOptions([
    'pageUid' => 1,
    'additionalParameters' => 'param1=value1&param2=value2',
]);
$formDefinition->addFinisher($redirectFinisher);

Options

pageUid

Data type
int
Mandatory
Yes
Default value
1
Description
Redirect to this page uid

additionalParameters

Data type
string
Mandatory
No
Default value
empty string
Description
Additional parameters which should be used on the target page

fragment

Data type
string
Mandatory
No
Default value
empty string
Description
Add a fragment (e.g. #c9 or #foo) to the redirect link. The `#’ character can be omitted.

delay

Data type
int
Mandatory
No
Default value
0
Description
The redirect delay in seconds.

statusCode

Data type
int
Mandatory
No
Default value
303
Description
The HTTP status code for the redirect. Default is “303 See Other”.

SaveToDatabase finisher

This finisher saves the data from a submitted form into a database table.

Usage within form definition.

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
...

Usage through code:

$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,
        ],
    ],
]);

or create manually (not preferred):

$saveToDatabaseFinisher = GeneralUtility::makeInstance(SaveToDatabaseFinisher::class);
$saveToDatabaseFinisher->setOptions([
    '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,
        ],
    ],
]);
$formDefinition->addFinisher($saveToDatabaseFinisher);

You can write options as an array to perform multiple database operations.

Usage within form definition.

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}'
...

Usage through code:

$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}'],
        ],
    ],
]);

or create manually (not preferred):

$saveToDatabaseFinisher = GeneralUtility::makeInstance(SaveToDatabaseFinisher::class);
$saveToDatabaseFinisher->setOptions([
    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}'],
        ],
    ],
]);
$formDefinition->addFinisher($saveToDatabaseFinisher);

This performs 2 database operations. One insert and one update. You can access the inserted uids through ‘{SaveToDatabase.insertedUids.<theArrayKeyNumberWithinOptions>}’ If you perform a insert operation, the value of the inserted database row will be stored within the FinisherVariableProvider. <theArrayKeyNumberWithinOptions> references to the numeric options.* key.

Options

table

Data type
string
Mandatory
Yes
Default value
null
Description
Insert or update values into this table.

mode

Data type
string
Mandatory
No
Default value
‘insert’
Possible values
insert/ update
Description

insert will create a new database row with the values from the submitted form and/or some predefined values. @see options.elements and options.databaseFieldMappings

update will update a given database row with the values from the submitted form and/or some predefined values. ‘options.whereClause’ is then required.

whereClause

Data type
array
Mandatory
Yes, if mode = update
Default value
empty array
Description
This where clause will be used for a database update action

elements

Data type
array
Mandatory
Yes
Default value
empty array
Description
Use options.elements to map form element values to existing database columns. Each key within options.elements has to match with a form element identifier. The value for each key within options.elements is an array with additional informations.

elements.<formElementIdentifier>.mapOnDatabaseColumn

Data type
string
Mandatory
Yes
Default value
undefined
Description
The value from the submitted form element with the identifier <formElementIdentifier> will be written into this database column.

elements.<formElementIdentifier>.skipIfValueIsEmpty

Data type
bool
Mandatory
No
Default value
false
Description
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 (think about password fields etc.). Empty means strings without content, whitespace is valid content.

elements.<formElementIdentifier>.saveFileIdentifierInsteadOfUid

Data type
bool
Mandatory
No
Default value
false
Description

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 (think about password fields etc.).

This setting only rules for form elements which creates a FAL object like FileUpload or ImageUpload. 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 (1:/user_uploads/some_uploaded_pic.jpg) instead.

elements.<formElementIdentifier>.dateFormat

Data type
string
Mandatory
No
Default value
‘U’
Description
If the internal datatype is \DateTime which is true for the form element types DatePicker and Date, the object needs to be converted into a string value. This option allows you to define the format of the date in case of such a conversion. You can use every format accepted by the PHP date() function (https://php.net/manual/en/function.date.php#refsect1-function.date-parameters). The default value is “U” which leads to a Unix timestamp.

databaseColumnMappings

Data type
array
Mandatory
No
Default value
empty array
Description

Use this to map database columns to static values. Each key within options.databaseColumnMappings has to match with an existing database column. The value for each key within options.databaseColumnMappings is an array with additional informations.

This mapping is done before the options.element mapping. This means if you map a database column to a value through options.databaseColumnMappings and map a submitted form element value to the same database column through options.element, the submitted form element value will override the value you set within options.databaseColumnMappings.

databaseColumnMappings.<databaseColumnName>.value

Data type
string
Mandatory
Yes
Default value
undefined
Description

The value which will be written to the database column. You can also use the FormRuntime accessor feature to access every getable property from the FormRuntime In short: use something like {<formElementIdentifier>} to get the value from the submitted form element with the identifier <formElementIdentifier>.

If you use the FormRuntime accessor feature within options.databaseColumnMappings, the functionality is nearly identical to the options.elements configuration variant.

databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty

Data type
bool
Mandatory
No
Default value
false
Description
Set this to true if the database column should not be written if the value from options.databaseColumnMappings.<databaseColumnName>.value is empty.