Field

A Field object represents a form field of a particular type. Each field has its own unique attributes and functionality. Whenever you're dealing with a field in your template, you're actually working with a Field object.

Attributes

Methods

Field Settings

The settings for a field will differ per-type, but the following are general settings applicable to all fields.

Agree

Calculations

Categories

Checkboxes

Date/Time

Dropdown

Email Address

Entries

File Upload

Heading

Hidden

Html

Multi-Line Text

Name

Number

Payment

This field's settings will differ depending on the Payment Integration chosen.

Phone

Products

Radio

Recipients

Repeater

Section

Signature

Single-Line Text

Table

Tags

Users

Variants

Custom Validation

You can add custom validation to field, to handle all manner of scenarios. To do this, you'll need to create a custom module to contain PHP code for the validation logic.

If you write your own plugin or module, you’ll want to use its init() method to subscribe to an event on the Submission object to add your validation rules. Your event listener can add additional validation rules (opens new window) for fields.

For example, let's say we have a field with a handle emailAddress which we'd like required. We could do this with the following.

use verbb\formie\elements\Submission;
use verbb\formie\events\SubmissionRulesEvent;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $event->rules[] = [['field:emailAddress'], 'required'];
});

Or, maybe we only want a field required when another field is a certain value.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $event->rules[] = [['field:emailAddress'], 'required', 'when' => function($model) {
        return $model->subscribeMe;
    }];
});

Here, we check if a field with handle subscribeMe is truthy, and if so make the emailAddress field required.

Another example could be limiting a field to be numeric, and a maximum length.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $event->rules[] = [['field:accountNumber'], 'number', 'integerOnly' => true, 'max' => 9];
});

You can also customise the validation message with number validation when using min/max with tooSmall and tooBig.

However, the above rules are applied to every submission, which will throw an error if you set a rule for a field that doesn't exist on the form for the submission you're creating. The above example assumes you have a field with the handle emailAddress for every form, which may not always be the case, especially if you have multiple forms.

Instead, you'll want to add a conditional check what form you're creating a submission on.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $form = $event->submission->getForm();

    // Only apply this custom validation for the form with handle `contactForm`
    if ($form->handle === 'contactForm') {
        $event->rules[] = [['field:emailAddress'], 'required'];
    }
});

If you have a lot of forms, or would rather not conditionally check every form for your site, you can loop through the available fields for the submission, to add a check whether the field exists. This can be useful if you want to enforce a validation for all email fields across your site, but not every form has an emailAddress field.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    foreach ($event->submission->getFields() as $field) {
        // Check against the handle of the field
        if ($field->handle === 'emailAddress') {
            $event->rules[] = [['field:emailAddress'], 'required'];
        }

        // Or, for a more global-check - against the type of the field
        if ($field instanceof \verbb\formie\fields\Email) {
            $event->rules[] = [['field:emailAddress'], 'required'];
        }
    }
});