DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Fields¶

The fields are the properties of a form's PHP model. For each field having a custom behaviour (for instance a validation rule), you must fill its TypoScript configuration.

Hint

By convention, every time a new common field is configured, its configuration should be set at the path config.tx_formz.fields; this way, it may be used again by another form. A good example of a common field is “email”: several forms may use this field with the exact same configuration.

Properties¶

You can find below the list of parameters usable by a field.

Property	Title
validation	Field validation rules
behaviours	Field behaviours
activation.conditions	Activation conditions
activation.expression	Field activation expression
settings.fieldContainerSelector	Field container selector
settings.messageContainerSelector	Message container selector
settings.messageListSelector	Message list container selector
settings.messageTemplate	Message template

Field validation¶

Property

validation

Required?

No

Description

Contains the list of validators and their rules used for the field's validation.

Validators will be evaluated following the order of their declaration.

Example:

config.tx_formz.fields.phoneNumber {
    validation {
        # The phone number is required.
        required < config.tx_formz.validators.required

        # The phone number must have 10 numbers.
        numberLength < config.tx_formz.validators.numberLength
        numberLength.options {
            minimum = 10
            maximum = 10
        }
    }
}

Note

Note that the validators configurations are fetched directly from config.tx_formz.validators. It prevents a configuration duplication when the validators are used at several places.

Field behaviours¶

Property

behaviours

Required?

No

Description

Contains the list of behaviours used by the field.

Example:

config.tx_formz.fields.email {
    behaviours {
        # Email address is switched to lower case.
        toLowerCase < config.tx_formz.behaviours.toLowerCase
    }
}

Note

Note that the validators configurations are fetched directly from config.tx_formz.behaviours. It prevents a configuration duplication when the behaviours are used at several places.

Activation conditions¶

Property

activation.conditions

Required?

No

Description

Contains the list of activation conditions which are then usable by this field only. Note that this list will be merged with the one from the property activationCondition of the form, as its usage is exactly the same: see “Conditions d'activation”.

Example:

activation {
    items {
        colorIsGreen {
            type = fieldHasValue
            fieldName = color
            fieldValue = green
        }
    }
}

Field activation¶

Property

activation.expression

Required?

No

Description

Contains the field activation condition: a logical expression to describe how the field is activated.

For more information on this, read the chapter “Activation”.

Example:

activation {
    condition = colorIsRed || colorIsBlue
}

Field container selector¶

Property

settings.fieldContainerSelector

Required?

No

Description

Contains the CSS selector which will be used to fetch the container containing the field. For instance, it may be a <fieldset> element.

Note that the marker #FIELD# is dynamically replaced by the name of the field.

The default value of this parameter is: [fz-field-container="#FIELD#"].

Example:

config.tx_formz.forms.MyVendor\MyExtension\Form\ExampleForm {
    fields {
        email {
            settings {
                fieldContainerSelector = [fz-field-container="#FIELD#"]
            }
        }

        firstName {
            settings {
                fieldContainerSelector = .names
            }
        }

        lastName {
            settings {
                fieldContainerSelector = .names
            }
        }
    }
}

Note

You can regroup several fields by assigning them the same container selector, as in the example above.

Message container selector¶

Property

settings.messageContainerSelector

Required?

No

Description

Contains the CSS selector which will be used to fetch the field message container.

Note that the marker #FIELD# is dynamically replaced by the name of the field.

The default value of this parameter is: [fz-field-message-container="#FIELD#"].

Example:

config.tx_formz.forms.MyVendor\MyExtension\Form\ExampleForm {
    fields {
        email {
            settings {
                messageContainerSelector = #errors-email
            }
        }
    }
}

Message list selector¶

Property

settings.messageListSelector

Required?

No

Description

Contains the CSS selector which will be used to fetch the block containing the field messages. It's a second selection layout for the message container (settings.messageContainerSelector): it allows adding static HTML contents which wont be cleaned up by JavaScript during the message refreshing.

Note that the marker #FIELD# is dynamically replaced by the name of the field.

The default value of this parameter is: [fz-field-message-list="#FIELD#"].

If an empty value is set, then the message container will be used.

Example:

config.tx_formz.forms.MyVendor\MyExtension\Form\ExampleForm {
    fields {
        email {
            settings {
                messageListSelector =
            }
        }
    }
}

Message template¶

Property

settings.messageTemplate

Required?

No

Description

HTML template used by JavaScript for the messages.

The default value of this parameter is:

<span class="js-validation-rule-#VALIDATOR# js-validation-type-#TYPE#
      js-validation-message-#KEY#">#MESSAGE#</span>

In the template, the following values are dynamically replaced:

#FIELD#: name of the field;
#FIELD_ID#: “id” attribute of the field. Note that for fields of type “radio” or “checkbox” using this marker is useless.
#VALIDATOR#: name of the validation rule which sent this message. For instance, it can be required;
#TYPE#: message type, often an error (in which case the value is error);
#KEY#: key of the sent message. Most of the time, it will be default;
#MESSAGE#: the message body.

Example:

config.tx_formz.forms.MyVendor\MyExtension\Form\ExampleForm {
    fields {
        email {
            settings {
                messageTemplate = <li class="#TYPE#">#MESSAGE#</li>
            }
        }
    }
}