Configuration 

A lot of configuration. Why? 

Building forms in a declarative and programmatic way is complex. Dynamic forms need program code that is as generic as possible. But generic program code means a lot of configurative overhead.

Having so much configuration may seem overwhelming, but it has a lot of advantages. Many aspects of EXT:form can be manipulated purely by configuration and without having to involve a developer.

The configuration in EXT:form is mainly located in places which make sense to a user. However, this means that certain settings have to be defined in multiple places in order to avoid unpredictable behaviour. There is no magic in the form framework - it is all about configuration.

Why YAML? 

Previous versions of EXT:form used a subset of TypoScript to describe form definitions and form element behavior. This led to a lot of confusion among integrators because the definition language looked like TypoScript but did not behave like TypoScript.

Form and form element definitions had to be declarative, so YAML was chosen as it is a declarative language.

YAML registration 

Currently, configuration using YAML is not natively integrated into the core of TYPO3. Because of this, YAML configuration has to be registered using TypoScript for the frontend (for webpages) and for the backend (for the form editor).

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

ExtensionManagementUtility::addTypoScriptSetup('
    module.tx_form {
       settings {
           yamlConfigurations {
               10 = EXT:form/Configuration/Yaml/FormSetup.yaml
           }
       }
    }
');

<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTypoScriptSetup('
    module.tx_form {
       settings {
           yamlConfigurations {
               1732785702 = EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
           }
       }
    }
');

YAML loading 

TYPO3 uses a 'YAML loader' for handling YAML, based on the Symfony YAML package. This YAML loader is able to resolve environment variables. In addition, EXT:form comes with its own YAML loader, but it has some restrictions, especially when resolving environment variables. This is for security reasons.

EXT:form differentiates between form configuration and form definition. A form definition can be stored in the file system (FAL) or can be shipped with an extension. The type of YAML loader used depends on the setup.

Configuration aspects 

Four things can be configured in EXT:form:

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

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

• clarity,
• increased performance, e.g. the form editor configuration is not needed in the frontend and is 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, frontend configuration is necessary in the backend in order for form preview to work correctly. When a form is rendered via the form plugin, the FormEngine configuration is needed to interpret overridden finisher configuration.

Inheritance 

The final YAML configuration does not produce one huge file. Instead, it is a sequential compilation process:

• Registered configuration files are parsed as YAML and are combined according to their order.
• 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.

Instead of inheritance, you can also extend/override the frontend configuration using TypoScript:

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

An example of overriding the basic EXT:form values is as follows. Make sure you have registered your own configuration file with:

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

Override the EXT:form Fluid templates with your own by defining your paths 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 in your own configuration file EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml will override the values in the basic configuration file in EXT:Form (EXT:form/Configuration/Yaml/FormSetup.yaml).

customEditor: &customEditor
  1761226183:
    identifier: custom
    templateName: Inspector-TextEditor
    label: Custom editor
    propertyPath: custom

otherCustomEditor: &otherCustomEditor
  identifier: otherCustom
  templateName: Inspector-TextEditor
  label: Other custom editor
  propertyPath: otherCustom

prototypes:
  standard:
    formElementsDefinition:
      Text:
        formEditor:
          editors:
            <<: *customEditor
            1761226184: *otherCustomEditor

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 form framework configuration is defined in prototypes. standard is the default prototype in EXT:form. Prototypes contain form element definitions - including frontend rendering, form editor and form plugin. When you create a new form, your form definition references a prototype configuration.

This allows you to do a lot of clever stuff. For example:

• depending on which prototype is referenced, the same form can load different

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

• in the form manager, depending on the selected prototype

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

The following use case illustrates the prototype concept. Imagine that two prototypes are defined: "noob" and "poweruser".