Adjusting Form Output

After working through this guide, you will have learned:

  • how to adjust the form output
  • how to create custom Form Presets
  • how to create custom form elements

Generally, this guide answers the question: How can form output be modified without programming?

Presets Explained

In the Quickstart guide, you have seen how a basic form can be built. We will now dissect the form element creation a little more, and explain the lines which you might not have understood yet.

Let’s have a look at the boilerplate code inside the form factory again:

public function build(array $factorySpecificConfiguration, $presetName) {
        $formConfiguration = $this->getPresetConfiguration($presetName);
        $form = new FormDefinition('contactForm', $formConfiguration);
        // ...
}

You see that the second parameter is a $presetName which is passed to getPresetConfiguration(). So, let’s introduce the concept of presets now.

A Preset is a container for pre-defined form configuration, and is the basic way to adjust the form’s output. Presets are defined inside the Settings.yaml file, like in the following example:

Neos:
  Form:
    presets:
      preset1:
        title: 'My First Preset'
        formElementTypes:
          'Neos.Form:SingleLineTextfield':
            # configuration for the single line textfield
      preset2:
        title: 'My Second Preset'
        parentPreset: 'preset1'
        # because preset2 *inherits* from preset1, only the changes between
        # preset1 and preset2 need to be defined here.

The above example defines two presets (preset1 and preset2). Because preset2 defines a parentPreset, it inherits all options from preset1 if not specified otherwise.

Tip

The Neos.Form package already defines a preset with the name default which contains all standard form elements. Look into Neos.Form/Configuration/Settings.yaml for the details on the defined form elements.

In most cases, you will create a sub-preset of the default preset, modifying only the parts you need.

The method getPresetConfiguration($presetName) in AbstractFormFactory evaluates the preset inheritance hierarchy and returns a merged array of the preset configuration.

Form Element Types Explained

Now that we have seen that presets can inherit from each other, let’s look inside the preset configuration. One particularily important part of each preset configuration is the form element type definition, which configures each form element correctly.

As an example, let’s create a text field with the following snippet:

$name = $page1->createElement('name', 'Neos.Form:SingleLineText');
$name->setLabel('Name');

In the above example, the form element type is Neos.Form:SingleLineText, and when creating the form element, it applies all default values being set inside the form element type. As an example, take the following type definition:

'Neos.Form:SingleLineText':
  defaultValue: 'My Default Text'
  properties:
    placeholder: 'My Placeholder Text'

That’s exactly the same as if one wrote the following PHP code:

$name->setDefaultValue('My Default Text');
$name->setProperty('placeholder', 'My Placeholder Text');

So $page->createElement($identifier, $formElementType) is essentially a very specialized factory method, which automatically applies the default values from the form element definition on the newly created form object before returning it.

Tip

The defaults are not only applied on single form elements, but also on the FormDefinition and Page objects. The FormDefinition object has, by convention, the form element type Neos.Form:Form, but you can also override it by passing the to-be-used type as third parameter to the constructor of FormDefinition.

A page has, by default, the form element type Neos.Form:Page, and you can override it by supplying a second parameter to the createPage() method of FormDefinition.

Supertypes

Now, there’s one more secret ingredient which makes the form framework powerful: Every form element type can have one or multiple supertypes; and this allows to only specify the differences between the “parent” form element and the newly created one, effectively creating an inheritance hierarchy of form elements.

The following example demonstrates this:

'Neos.Form:SingleLineText':
  defaultValue: 'My Default Text'
  properties:
    placeholder: 'My Placeholder Text'
'Neos.Form:SpecialText':
  superTypes:
    'Neos.Form:SingleLineText' : TRUE
  defaultValue: 'My special text'

Here, the SpecialText inherits the placeholder property from the SingleLineText and only overrides the default value.

Together, presets (with parent presets) and form element types (with supertypes) form a very flexible foundation to customize the rendering in any imaginable way, as we will explore in the remainder of this guide.

Note

If multiple super types are specified, they are evaluated from left to right, i.e. later super types override previous definitions.

Previously the superTypes configuration was just a simple list of strings:

'Neos.Form:SpecialText':
  superTypes:
    'Neos.Form:SingleLineText': TRUE
  defaultValue: 'My special text'

But this made it impossible to unset a super type from a 3rd party package. The old syntax is still supported but is deprecated and might be removed in future versions.

Creating a Custom Preset

First, we create a sub-preset inheriting from the default preset. For that, open up Your.Package/Configuration/Settings.yaml and insert the following contents:

Neos:
  Form:
    presets:
      myCustom:
        title: 'Custom Elements'
        parentPreset: 'default'

You now created a sub preset named myCustom which behaves exactly the same as the default preset. If you now specify the preset name inside the <form:render> ViewHelper you will not see any differences yet:

<form:render factoryClass="..." presetName="myCustom" />

Now we are set up to modify the custom preset, and can adjust the form output.

Adjusting a Form Element Template

The templates of the default Form Elements are located in Neos.Form/Resources/Private/Form/. They are standard Fluid templates and most of them are really simple. Open up the Single-Line Text template for example:

<f:layout name="Neos.Form:Field" />
<f:section name="field">
   <f:form.textfield property="{element.identifier}" id="{element.uniqueIdentifier}"
                     placeholder="{element.properties.placeholder}" errorClass="error" />
</f:section>

As you can see, the Form Element templates use layouts in order to reduce duplicated markup.

Tip

The Fluid Form Renderer expects layout and partial names in the format <PackageKey>:<Name>. That makes it possible to reference layouts and partials from other packages!

We’ll see how to change the layout in the next section. For now let’s try to simply change the class attribute of the SingleLineText element.

For that, copy the default template to Your.Package/Private/Resources/CustomElements/SingleLineText.html and adjust it as follows:

<f:layout name="Neos.Form:Field" />
<f:section name="field">
   <f:form.textfield property="{element.identifier}" id="{element.uniqueIdentifier}"
                     placeholder="{element.properties.placeholder}" errorClass="error"
                   class="customClass" />
</f:section>

Now, you only need to tell the framework to use your newly created template instead of the default one. This can be archieved by overriding the rendering option templatePathPattern in the form element type definition.

Adjust Your.Package/Configuration/Settings.yaml accordingly:

Neos:
  Form:
    presets:
      myCustom:
        title: 'Custom Elements'
        parentPreset: 'default'
        formElementTypes:
          'Neos.Form:SingleLineText':
            renderingOptions:
              templatePathPattern: 'resource://Your.Package/Private/CustomElements/SingleLineText.html'

Now, all Single-Line Text elements will have a class attribute of customClass when using the myCustom preset.

A more realistic use-case would be to change the arrangement of form elements. Read on to see how you can easily change the layout of a form.

Changing The Form Layout

By default, validation errors are rendered next to each form element. Imagine you want to render validation errors of the current page above the form instead. For this you need to adjust the previously mentioned field layout.

The provided default field layout located in Neos.Form/Resources/Private/Form/Layouts/Field.html is a bit more verbose as it renders the label, validation errors and an asterisk if the element is required (we slightly reformatted the template here to improve readability):

{namespace form=Neos\Form\ViewHelpers}
<f:form.validationResults for="{element.identifier}">
   <!-- wrapping div for the form element; contains an identifier for the form element if we are
      in preview mode -->
   <div class="clearfix{f:if(condition: validationResults.flattenedErrors, then: ' error')}"
        <f:if condition="{element.rootForm.renderingOptions.previewMode}">
           data-element="{form:form.formElementRootlinePath(renderable:element)}"
        </f:if>
   >
      <!-- Label for the form element, and required indicator -->
      <label for="{element.uniqueIdentifier}">{element.label -> f:format.nl2br()}
         <f:if condition="{element.required}">
            <f:render partial="Neos.Form:Field/Required" />
         </f:if>
       </label>

      <!-- the actual form element -->
      <div class="input">
         <f:render section="field" />

         <!-- validation errors -->
         <f:if condition="{validationResults.flattenedErrors}">
            <span class="help-inline">
               <f:for each="{validationResults.errors}" as="error">
                  {error -> f:translate(id: error.code, arguments: error.arguments,
                                        package: 'Neos.Form', source: 'ValidationErrors')}
                  <br />
               </f:for>
            </span>
         </f:if>
      </div>
   </div>
</f:form.validationResults>

Copy the layout file to Your.Package/Private/Resources/CustomElements/Layouts/Field.html and remove the validation related lines:

{namespace form=Neos\Form\ViewHelpers}
<f:form.validationResults for="{element.identifier}">
   <!-- wrapping div for the form element; contains an identifier for the form element if we are
      in preview mode -->
   <div class="clearfix{f:if(condition: validationResults.flattenedErrors, then: ' error')}"
        <f:if condition="{element.rootForm.renderingOptions.previewMode}">
           data-element="{form:form.formElementRootlinePath(renderable:element)}"
        </f:if>
   >
      <!-- Label for the form element, and required indicator -->
      <label for="{element.uniqueIdentifier}">{element.label -> f:format.nl2br()}
         <f:if condition="{element.required}">
            <f:render partial="Neos.Form:Field/Required" />
         </f:if>
       </label>

      <!-- the actual form element -->
      <div class="input">
         <f:render section="field" />
      </div>
   </div>
</f:form.validationResults>

Additionally you need to adjust the default form template located in Neos.Form/Resources/Private/Form/Form.html (remember that a FormDefinition also has a form element type, by default of Neos.Form:Form), which looks as follows by default:

{namespace form=Neos\Form\ViewHelpers}
<form:form object="{form}" action="index" method="post" id="{form.identifier}"
           enctype="multipart/form-data">
   <form:renderRenderable renderable="{form.currentPage}" />
   <div class="actions">
      <f:render partial="Neos.Form:Form/Navigation" arguments="{form: form}" />
   </div>
</form:form>

Copy this template file to Your.Package/Private/Resources/CustomElements/Form.html and add the validation result rendering:

{namespace form=Neos\Form\ViewHelpers}
<form:form object="{form}" action="index" method="post" id="{form.identifier}"
           enctype="multipart/form-data">
   <f:form.validationResults>
      <f:if condition="{validationResults.flattenedErrors}">
         <ul class="error">
            <f:for each="{validationResults.flattenedErrors}" as="elementErrors"
                   key="elementIdentifier" reverse="true">
               <li>
                  {elementIdentifier}:
                  <ul>
                     <f:for each="{elementErrors}" as="error">
                        <li>{error}</li>
                     </f:for>
                  </ul>
               </li>
            </f:for>
         </ul>
      </f:if>
   </f:form.validationResults>
   <form:renderRenderable renderable="{form.currentPage}" />
   <div class="actions">
      <f:render partial="Neos.Form:Form/Navigation" arguments="{form: form}" />
   </div>
</form:form>

Now, you only need to adjust the form definition in order to use the new templates:

Neos:
  Form:
    presets:
      ########### CUSTOM PRESETS ###########

      myCustom:
        title: 'Custom Elements'
        parentPreset: 'default'
        formElementTypes:

           # ...

           ### override template path of Neos.Form:Form ###
          'Neos.Form:Form':
            renderingOptions:
              templatePathPattern: 'resource://Neos.FormExample/Private/CustomElements/Form.html'

           ### override default layout path ###
          'Neos.Form:Base':
            renderingOptions:
              layoutPathPattern: 'resource://Neos.FormExample/Private/CustomElements/Layouts/{@type}.html'

Tip

You can use placeholders in templatePathPattern, partialPathPattern and layoutPathPattern: {@package} will be replaced by the package key and {@type} by the current form element type without namespace. A small example shall illustrate this:

If the form element type is Your.Package:FooBar, then {@package} is replaced by Your.Package, and {@type} is replaced by FooBar. As partials and layouts inside form elements are also specified using the Package:Type notation, this replacement also works for partials and layouts.

Creating a New Form Element

With the Form Framework it is really easy to create additional Form Element types. Lets say you want to create a specialized version of the Neos.Form:SingleSelectRadiobuttons that already provides two radio buttons for Female and Male. That’s just a matter of a few lines of yaml:

Neos:
  Form:
    presets:
       ########### CUSTOM PRESETS ###########

      myCustom:
        title: 'Custom Elements'
        parentPreset: 'default'
        formElementTypes:

           # ...

          'Your.Package:GenderSelect':
            superTypes:
              'Neos.Form:SingleSelectRadiobuttons': TRUE
            renderingOptions:
              templatePathPattern: 'resource://Neos.Form/Private/Form/SingleSelectRadiobuttons.html'
            properties:
              options:
                f: 'Female'
                m: 'Male'

As you can see, you can easily extend existing Form Element Definitions by specifying the superTypes.

Tip

We have to specify the templatePathPattern because according to the default path pattern the template would be expected at Your.Package/Private/Resources/Form/GenderSelect.html otherwise.

Note

Form Elements will only be available in the preset they’re defined (and in it’s sub-presets). Therefore you should consider adding Form Elements in the default preset to make them available for all Form Definitions extending the default preset.