Verbb

​
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#

AttributeDescription
idID of the field.
labelThe label of the field.
handleThe handle of the field.
typeThe type of the field.
formThe Form this field belongs to.
formIdThe Form ID for the form this field belongs to.
rowIdThe Row ID for the row this field belongs to.
rowIndexThe Row index for the row this field belongs to. This is used for field ordering.
settingsA collection of settings for the field. See Field Settings.

​
Methods#

MethodDescription
getSvgIcon()Returns the contents of an SVG icon used for a field type.
getSvgIconPath()Returns the path to the SVG icon used for a field type.
getIsNew()Denotes whether this field is new.
hasLabel()Whether the field has a label or not. Some fields do not have one.
getHtmlId()Returns a string for the id HTML attribute when rendering the field.
getHtmlDataId()Returns a string as a data-id HTML attribute with the field handle.
getHtmlName()Returns a string for the name HTML attribute when rendering the field.
getExtraBaseFieldConfig()Returns any base-level configuration data for the field.
getFieldDefaults()Returns any defaults for the field, when it's created.
getContainerAttributes()Returns an array of options for container attributes.
getInputAttributes()Returns an array of options for input attributes.
renderHtmlTag()Returns a HtmlTag object for a provided theming key.
defineHtmlTag()Allows fields to define what HtmlTag objects it should use.
getParentField()Returns the parent field, if applicable. Only set for sub-field and nested-field types.
setParentField()Sets the parent field instance, including applicable namespace.
getFrontEndInputHtml()Returns the HTML for a the front-end template for a field.
getFrontEndInputOptions()Returns an object of variables that can be used for front-end fields.
getEmailHtml()Returns the HTML for an email notification for a field.
afterCreateField()A function called after a field has been created in the control panel.

​
Field Settings#

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

AttributeDescription
labelPositionThe position of the field's label.
instructionsPositionThe position of the field's instructions.
cssClassesAny CSS classes, applied on the outer container of a field.
containerAttributesA collection of attributes added to the outer container of a field.
inputAttributesA collection of attributes added to the input element of a field - where applicable.

​
Agree#

SettingDescription
descriptionThe description for the field. This will be shown next to the checkbox.
descriptionHtmlThe HTML description for the field.
checkedValue The value of this field when it is checked.
uncheckedValueThe value of this field when it is unchecked.
defaultValueThe default value for the field when it loads.

​
Calculations#

SettingDescription
formulaThe raw formula used in the field, before it's been parsed.
MethodDescription
getFormula()Returns the parsed formula, given the current submission's context.

​
Categories#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourceWhich source do you want to select categories from?
branchLimitLimit the number of selectable category branches.
rootCategoryThe category to act as the root, if set.
showStructureWhether the structure of categories should be shown.

​
Checkboxes#

SettingDescription
optionsDefine the available options for users to select from.
layoutSelect which layout to use for these fields.
toggleCheckboxWhether to add an additional checkbox to toggle all checkboxes in this field by. Either null, top, bottom.
toggleCheckboxLabelThe label for the toggle checkbox field.

​
Date/Time#

SettingDescription
defaultValueEntering a default value will place the value in the field when it loads.
displayTypeThe display layout for this field. Either calendar, dropdowns or inputs.
dateFormatThe chosen format for the date.
timeFormatThe chosen format for the time.
useDatePickerWhether this field should use the Flatpickr datepicker.
datePickerOptionsA collection of options for the Flatpickr datepicker.
minDateThe minimum allowed date.
maxDateThe maximum allowed date.
SettingDescription
multipleWhether this field should allow multiple options to be selected.
optionsDefine the available options for users to select from.

​
Email Address#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
validateDomainWhether to validate the domain when the value is saved.
blockedDomainsA list of domains to block values from.
uniqueValueWhether to the value of this field should be unique across all submissions for the form.

​
Entries#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourcesWhich sources do you want to select entries from?
limitLimit the number of selectable entries.

​
File Upload#

SettingDescription
uploadLocationSourceThe volume for files to be uploaded into.
uploadLocationSubpathThe sub-path for the files to be uploaded into.
limitFilesLimit the number of files a user can upload.
sizeLimitLimit the size of the files a user can upload.
allowedKindsA collection of allowed mime-types the user can upload.

​
Heading#

SettingDescription
headingSizeChoose the size for the heading.

​
Hidden#

SettingDescription
defaultOptionThe selected option for the preset default value chosen.
defaultValueEntering a default value will place the value in the field when it loads. This will be dependant on the value chosen for the defaultOption.
queryParameterIf query string is selected for the defaultOption, this will contain the query string parameter to look up.
cookieNameIf cookie is selected for the defaultOption, this will contain the cookie name to look up.

​
Html#

SettingDescription
htmlContentEnter HTML content to be rendered for this field.

​
Multi-Line Text#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
limitWhether to limit the content of this field.
minTypeThe field’s minimum text type. Either characters or words.
minThe field’s minimum number of characters/words to limit, based on minType.
maxTypeThe field’s maximum text type. Either characters or words.
maxThe field’s maximum number of characters/words, based on maxType.
useRichTextWhether the front-end of the field should use a Rich Text editor. This is powered by Pell (opens new window).
richTextButtonsAn array of available buttons the Rich Text field should use. Consult the Pell (opens new window) docs for these options.

​
Name#

SettingDescription
useMultipleFieldsWhether this field should use multiple fields for users to enter their details.

​
Number#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
limitWhether to limit the numbers for this field.
minThe minimum number that can be entered for this field.
maxThe maximum number that can be entered for this field.
decimalsSet the number of decimal points to format the field value.

​
Payment#

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

SettingDescription
paymentIntegrationThe handle of the Payment Integration chosen.
paymentIntegrationTypeThe class of the Payment Integration chosen.
providerSettingsA collection of settings for the payment provider to use.
MethodDescription
getPaymentIntegration()Returns the Payment Integration for the field.
getPaymentHtml()Returns the HTML for the front-end field.
getFrontEndJsModules()Returns the JavaScript modules for the front-end field.

​
Phone#

SettingDescription
countryAllowedA collection of allowed countries.
countryDefaultValueThe default value for the Country sub-field.
countryEnabledWhether the Country sub-field is enabled in the control panel.

​
Products#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourcesWhich sources do you want to select products from?
limitLimit the number of selectable products.

​
Radio#

SettingDescription
optionsDefine the available options for users to select from.
layoutSelect which layout to use for these fields. Either vertical or horizontal,

​
Recipients#

SettingDescription
displayTypeWhat sort of field to show on the front-end for users. Either hidden, dropdown, checkboxes or radio.
optionsDefine the available options for users to select from.

​
Repeater#

SettingDescription
addLabelThe label for the button that adds another instance.
minRowsThe minimum required number of instances of this repeater's fields that must be completed.
maxRowsThe maximum required number of instances of this repeater's fields that must be completed.

​
Section#

SettingDescription
borderAdd a border to this section.
borderWidthSet the border width (in pixels).
borderColorSet the border color.

​
Signature#

SettingDescription
backgroundColorSet the background color.
penColorSet the pen color.
penWeightSet the line thickness (weight) for the pen.

​
Single-Line Text#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
limitWhether to limit the content of this field.
minTypeThe field’s minimum text type. Either characters or words.
minThe field’s minimum number of characters/words to limit, based on minType.
maxTypeThe field’s maximum text type. Either characters or words.
maxThe field’s maximum number of characters/words, based on maxType.

​
Table#

SettingDescription
columnsDefine the columns your table should have.
defaultsDefine the default values for the field.
addRowLabelThe label for the button that adds another row.
staticWhether this field should disallow adding more rows, showing only the default rows.
minRowsThe minimum required number of rows in this table that must be completed.
maxRowsThe maximum required number of rows in this table that must be completed.

​
Tags#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourceWhich source do you want to select tags from?

​
Users#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourcesWhich sources do you want to select users from?
limitLimit the number of selectable users.

​
Variants#

SettingDescription
placeholderThe option shown initially, when no option is selected.
source Which source do you want to select variants from?
limitLimit the number of selectable 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.

Make sure you’re comfortable creating a plugin or module for Craft CMS (opens new window). Take a look at this Knowledge Base (opens new window) article for a complete example.

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'];
        }
    }
});

Previous ← Row Next Submission →