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:
      contentElementUid: 9
...

Usage through code:

$formDefinition->createFinisher('Confirmation', [
    'contentElementUid' => 9,
]);

or create manually (not preferred):

$confirmationFinisher = GeneralUtility::makeInstance(ConfirmationFinisher::class);
$confirmationFinisher->setOptions([
    'contentElementUid' => 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 'da' 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\Type\ContextualFeedbackSeverity::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\Type\ContextualFeedbackSeverity::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: \TYPO3\CMS\Core\Type\ContextualFeedbackSeverity::OK (0)
Description: The flash message severity code. See EXT:core/Classes/Type/ContextualFeedbackSeverity.php (GitHub) cases 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
          hashed: 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,
            'hashed' => 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,
            'hashed' => 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 an 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>.hashed

Data type: bool
Mandatory: No
Default value: false
Description: Set this to true if the value from the submitted form element should be hashed before writing into the database.

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.