Finishers¶

Accessing form runtime values¶

By utilizing a specific notation, finisher options can be populated with submitted form values (assuming you are using the parseOption() method). You can access values of the FormRuntime and thus values of each single form element by encapsulating the option values with {}. If there is a form element with the identifier 'subject', you can access its value within the finisher configuration. Check out the following example to get the whole idea.

identifier: simple-contact-form
label: 'Simple Contact Form'
prototype: standard
type: Form

finishers:
  -
    identifier: Custom
    options:
      yourCustomOption: '{subject}'

renderables:
  -
    identifier: subject
    label: 'Subject'
    type: Text

// $yourCustomOption contains the value of the form element with the
// identifier 'subject'
$yourCustomOption = $this->parseOption('yourCustomOption');

In addition, you can use {__currentTimestamp} as a special option value. It will return the current UNIX timestamp.

Share data between finishers¶

The method getFinisherVariableProvider returns an object (TYPO3\CMS\Form\Domain\Finishers\FinisherVariableProvider) which allows you to store data and transfer it to other finishers. The data can be easily accessed programmatically or within your configuration:

$this->finisherContext->getFinisherVariableProvider();

The data is stored within the FinisherVariableProvider and is addressed by a user-defined 'finisher identifier' and a custom option value path. The name of the 'finisher identifier' should consist of the name of the finisher without the potential 'Finisher' appendix. If your finisher is derived from the class TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher, the name of this construct is stored in the following variable:

$this->shortFinisherIdentifier

For example, if the name of your finisher class is 'CustomFinisher', the mentioned variable will contain the value 'Custom'.

There are a bunch of methods to access and manage the finisher data:

• Add data:

  $this->finisherContext->getFinisherVariableProvider()->add(
      $this->shortFinisherIdentifier,
      'unique.value.identifier',
      $value
  );

  Copied!

• Get data:

  $this->finisherContext->getFinisherVariableProvider()->get(
      $this->shortFinisherIdentifier,
      'unique.value.identifier',
      'default value'
  );

  Copied!

• Check the existence of data:

  $this->finisherContext->getFinisherVariableProvider()->exists(
      $this->shortFinisherIdentifier,
      'unique.value.identifier'
  );

  Copied!

• Delete data:

  $this->finisherContext->getFinisherVariableProvider()->remove(
      $this->shortFinisherIdentifier,
      'unique.value.identifier'
  );

  Copied!

In this way, each finisher can access data programmatically. Moreover, it is possible to retrieve the data via configuration, provided that a finisher stores the values within the FinisherVariableProvider.

Assuming that a finisher called 'Custom' sets data as follows:

$this->finisherContext->getFinisherVariableProvider()->add(
    $this->shortFinisherIdentifier,
    'unique.value.identifier',
    'Wouter'
);

... you are now able to access the value 'Wouter' via {Custom.unique.value.identifier} in any other finisher.

identifier: sample-form
label: 'Simple Contact Form'
prototype: standard
type: Form

finishers:
  -
    identifier: Custom
    options:
      yourCustomOption: 'Frans'

  -
    identifier: SomeOtherStuff
    options:
      someOtherCustomOption: '{Custom.unique.value.identifier}'

Add finisher to backend UI¶

After adding a custom finisher you can also add the finisher to the form editor GUI to let your backend users configure it visually. Add the following to the backend yaml setup:

prototypes:
  standard:
    formElementsDefinition:
      Form:
        formEditor:
          editors:
            900:
              # Extend finisher drop down
              selectOptions:
                35:
                  value: 'CustomFinisher'
                  label: 'Custom Finisher'
          propertyCollections:
            finishers:
               # add finisher fields
               25:
                  identifier: 'CustomFinisher'
                  editors:
                     __inheritances:
                        10: 'mixins.formElementMixins.BaseCollectionEditorsMixin'
                     100:
                       label: "Custom Finisher"
                     # custom field (input, required)
                     110:
                       identifier: 'customField'
                       templateName: 'Inspector-TextEditor'
                       label: 'Custom Field'
                       propertyPath: 'options.customField'
                       propertyValidators:
                         10: 'NotEmpty'
                     # email field
                     120:
                       identifier: 'email'
                       templateName: 'Inspector-TextEditor'
                       label: 'Subscribers email'
                       propertyPath: 'options.email'
                       enableFormelementSelectionButton: true
                       propertyValidators:
                         10: 'NotEmpty'
                         20: 'FormElementIdentifierWithinCurlyBracesInclusive'

       finishersDefinition:
         CustomFinisher:
           formEditor:
             iconIdentifier: 'form-finisher'
             label: 'Custom Finisher'
             predefinedDefaults:
               options:
                 customField: ''
                 email: ''
           # displayed when overriding finisher settings
           FormEngine:
             label: 'Custom Finisher'
             elements:
               customField:
                 label: 'Custom Field'
                 config:
                   type: 'text'
               email:
                 label: 'Subscribers email'
                 config:
                   type: 'text'

Make sure the setup file is registered in the backend:

module.tx_form.settings.yamlConfigurations {
   123456789 = EXT:yourExtension/Configuration/Form/Backend.yaml
}