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

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