Configuration

A lot of configuration. Why?

The requirements for building forms in a declarative and programmatic way are complex. What we have learned so far is that the program code must be kept as generic as possible to handle the dynamics of forms, but a generic program code means a lot of configurative overhead.

Initially, the configuration may overwhelm you, but it also has some great advantages. Many aspects of EXT:form can be manipulated in a purely configurative manner without involving a developer.

Furthermore, we wanted to avoid the configuration being done at places whose context actually suggests something different. This pedantry, however, leads to the situation in which certain settings have to be defined multiple times at multiple places. This may seem nonsensical, but it avoids unpredictable behaviour. Within the form framework, nothing happens magically. It is all about configuration.

Why YAML?

Former versions of EXT:form used a subset of TypoScript to describe the definition of a specific form and the behaviour of the included form elements. This led to a lot of confusion from integrators because the implemented definition language looked like TypoScript but did not behave like TypoScript.

Since the definition of forms and form elements must be declarative, the EXT:form team decided to use YAML. Just through the visual appearance of YAML, it should be clear to everyone that neither magic nor TypoScript stdWrap functionality are possible.

YAML registration

At the moment, configuration via YAML is not natively integrated into the core of TYPO3. You have to make a short detour by using TypoScript in order to register your YAML configuration. Furthermore, there is a "speciality" regarding the integration of your YAML configuration for the backend module.

plugin.tx_form {
    settings {
        yamlConfigurations {
            10 = EXT:form/Configuration/Yaml/FormSetup.yaml
        }
    }
}

plugin.tx_form {
    settings {
        yamlConfigurations {
            100 = EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
        }
    }
}

module.tx_form {
    settings {
        yamlConfigurations {
            10 = EXT:form/Configuration/Yaml/FormSetup.yaml
        }
    }
}

module.tx_form {
    settings {
        yamlConfigurations {
            100 = EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
        }
    }
}

defined('TYPO3') or die();

call_user_func(function () {
     \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTypoScriptSetup(
         trim('
             module.tx_form {
                 settings {
                     yamlConfigurations {
                         100 = EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
                     }
                 }
             }
         ')
     );
});

YAML loading

TYPO3 is using a custom 'YAML loader' for handling YAML in TYPO3 based on the Symfony YAML package. This YAML loader is able to resolve environment variables. In addition, EXT:form comes with an own YAML loader which has some limitations/ restrictions, especially when it comes to resolve environment variables. Those limitations are necessary security-wise.

EXT:form differentiates between form configuration and form definition. In addition, a form definition can be stored in the file system (FAL) or can be shipped with a custom extension. Depending on those parameters different YAML loaders are used and thus, different features are available.

Configuration aspects

In EXT:form, four aspects can be configured:

• the behaviour of the frontend rendering,
• the behaviour of the form editor,
• the behaviour of the form manager, and
• the behaviour of the form plugin.

Those aspects are defined in separate files which are only loaded in the frontend/ backend when needed. This approach has two advantages:

• increased clarity,
• increased performance, e.g. the form editor configuration is not needed in the frontend and therefore not loaded.

It is up to you if you want to follow this guideline or if you want to put the whole configuration into one large file.

There are some configurational aspects which cannot explicitly be assigned to either the frontend or the backend. Instead, the configuration is valid for both areas. For example, within the backend, the whole frontend configuration is required in order to allow the form preview to work properly. In addition, as soon as the form is rendered via the `form plugin``, the ``FormEngine` configuration is needed to interpret the overridden finisher configuration correctly.

Inheritances

The final YAML configuration is not based on one huge file. Instead, it is a compilation of a sequential process:

• First of all, all registered configuration files are parsed as YAML and are overlaid according to their order.
• After that, the __inheritances operator is applied. It is a unique operator introduced by the form framework.
• Finally, all configuration entries with a value of null are deleted.

Additionally, the frontend configuration can be extended/ overridden by TypoScript:

plugin.tx_form {
    settings {
        yamlSettingsOverrides {
            ...
        }
    }
}

For example, if you want to override the fluid templates and you therefore register an additional configuration file via

plugin.tx_form {
    settings {
        yamlConfigurations {
            # register your own additional configuration
            # choose a number higher than 30 (below is reserved)
            100 = EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
        }
    }
}

... you only have to define the following YAML setup in EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml:

prototypes:
  standard:
    formElementsDefinition:
      Form:
        renderingOptions:
          templateRootPaths:
            20: 'EXT:my_site_package/Resources/Private/Templates/Form/Frontend/'
          partialRootPaths:
            20: 'EXT:my_site_package/Resources/Private/Partials/Form/Frontend/'
          layoutRootPaths:
            20: 'EXT:my_site_package/Resources/Private/Layouts/Form/Frontend/'

The values of your own configuration file will overrule the corresponding values of the basic configuration file (EXT:form/Configuration/Yaml/FormSetup.yaml).

Form:
  part01:
    key01: value
    key02:
      key03: value
  part02:
    __inheritances:
      10: Form.part01

Form:
  part01:
    key01: value
    key02:
      key03: value
  part02:
    key01: value
    key02:
      key03: value

Form:
  part01:
    key: value
  part02:
    __inheritances:
      10: Form.part01
    key: 'value override'

Form:
  part01:
    key: value
  part02:
    key: 'value override'

prototypes:
  standard:
    formElementsDefinition:
      GenderSelect:
        __inheritances:
          10: 'prototypes.standard.formElementsDefinition.RadioButton'
        renderingOptions:
          templateName: 'RadioButton'
        properties:
          options:
            f: 'Female'
            m: 'Male'
            u: 'Unicorn'
            a: 'Alien'

Prototypes

Most of the configurational aspects of the form framework are defined in so-called prototypes. By default, EXT:form defines a prototype named standard. The definition of form elements - including their rendering in the frontend, form editor and form plugin - reside within those prototypes. As soon as you create a new form, the specific form definition references such a prototype.

This allows you to do a lot of nifty stuff. Let your imagination run free. For example:

• based on the referenced prototype, the same form can load

  • ...varying templates
  • ...varying form editor configurations
  • ...varying form plugin finisher overrides

• within the form manager, depending on the selected prototype

  • ...varying form editor configurations can be loaded
  • ...varying pre-configured form templates (boilerplates) can be chosen
• different prototypes can define different/ extended form elements and display them in the frontend/ form editor accordingly

Check out the following use case to fully understand the concept behind prototypes. Imagine that there are two defined prototypes: "noob" and "poweruser".