Skip to main content

Field object

Each field object contains the metadata specified in form builder for the specific form it resides in. It can render its label, input field, instructions and errors out of the box.

​Properties

  • id #

  • handle #

  • label #

  • instructions #

  • required: true #

    • A boolean value. true if the field is required.

  • errors #

    • An array of error message strings if any are present after submitting the form.

  • pageIndex #

    • A number representing the page index this field resides on.

  • customAttributes #

    • An object of customizable attributes to ease the customizability of render methods.
    • Contains the following properties (each one is null if not set).
      • id #
        • The ID attribute of the HTML input field for renderInput().
        • When used on renderLabel(), it will replace the default for attribute value.
      • class #
        • The CLASS attribute of the HTML input field for renderInput().
      • labelClass #
        • The CLASS attribute of the HTML label field for renderLabel().
      • errorClass #
        • The CLASS attribute of the errors HTML list for renderErrors().
      • instructionsClass #
        • The CLASS attribute of the instructions HTML field for renderInstructions().
      • instructionsBelowField #
        • A boolean value.
        • Set to true to render instructions below, not above the input field when using the render() method.
      • overrideValue #
        • An override value for the field's defaultValue in case you need a context specific default value.
      • inputAttributes #
        • An object of attributes which will be added to the input field. If the form has inputAttributes specified, the attributes will be merged together with field inputAttributes taking precedence over form's inputAttributes.
        • Ex: inputAttributes: { "readonly": true, "data-field-id": "test" }
      • useRequiredAttribute: true #
        • Adds required attribute to input fields that have been set to be required in Composer.

  • value #

    • The default or posted value of the field.
    • Can be a string, number or array (it's an array only for checkbox_group and email fields)

  • valueAsString #

    • The value value cast as a string.
    • Array values get joined via a , separator.
    • Uses the selected option labels for checkbox_group and radio_group.
      • Use getValueAsString(false) to use selected option values instead.

  • type #

    • Type of the field:
      • text
      • textarea
      • hidden
      • select
      • checkbox
      • checkbox_group
      • radio_group
      • email
      • dynamic_recipients
      • file
      • mailing_list
      • html
      • submit
      • number
      • ratingPro

  • rulesHtmlData #

    • Parses the necessary code for Conditional Rules feature.
    • Should be used in automated form rendering, placed on the div wrapper for each field inside of {% for field in row %}.
      • E.g. <div class="{{ columnClass }}"{{ field.rulesHtmlData }}>
    • Will render a data-ff-rule attribute along with the necessary string to work with Freeform's inserted JS for Rules feature, e.g. data-ff-rule='{"show":true,"type":"any","criteria":[{"tgt":"firstName","o":"=","val":"Bob"}]}'.

​Field Specific Properties

The following are field specific properties for the basic field types (see below for additional Pro Field Types):

  • text #
    • placeholder
  • textarea #
    • placeholder
  • number #
    • placeholder
    • minLength
    • maxLength
    • minValue
    • maxValue
    • decimalCount
    • decimalSeparator (e.g. .)
    • thousandsSeparator (e.g. ,)
    • allowNegative (e.g. false)
  • select #
    • options
      • An array of option objects with label and value properties.
  • multiple_select #
    • options
      • An array of option objects with label and value properties.
  • checkbox #
    • Has a default value of Yes, which can be overwritten with any value you want. The front end however, will always display the value as 1, but upon submission, the value will be switched to the one you have set.
  • checkbox_group #
    • options
      • An array of option objects with label and value properties.
  • radio_group #
    • options
      • An array of option objects with label and value properties.
  • submit #
    • labelNext
      • A label for the Next button. Submit by default.
    • labelPrev
      • A label for the Previous button. Previous by default.
    • disablePrev
      • A boolean value. If true the Previous button should not be rendered.
  • dynamic_recipients #
    • showAsRadio
      • A boolean value. If true the dynamic recipients field should be rendered as radio buttons instead of a select field.
    • showAsCheckboxes
      • A boolean value. If true the dynamic recipients field should be rendered as checkboxes instead of a select field.
    • notificationId
      • The database ID of the assigned Email Notification Template.
    • NOTE: When parsing this field semi-manually, be sure to use loop.index0 to generate numeric values of options instead of fieldName.value.
  • email #
    • placeholder
    • notificationId
      • The database ID of the assigned Email Notification Template.
  • file #
    • fileKinds
      • An array of allowed file kinds, e.g. image, document, audio, etc.
    • maxFileSizeKB
      • The numeric representation of the upload limit in kilobytes.
    • fileCount
      • The maximum number of allowed files to be uploaded.
      • Specify a number larger than 1 to allow multiple files to be uploaded at the same time.

​Pro Field Specific Properties

The following are field specific properties for Freeform Pro additional field types:

  • confirmation (Legacy, please see Confirm special field)
    • placeholder
  • datetime #
    • initialValue
    • dateTimeType (e.g. both)
    • generatePlaceholder (e.g. true)
    • dateOrder (e.g. ymd)
    • date4DigitYear (e.g. true)
    • dateLeadingZero (e.g. true)
    • dateSeparator (e.g. /)
    • clock24h (e.g. false)
    • lowercaseAMPM (e.g. true)
    • clockSeparator (e.g. :)
    • clockAMPMSeparate (e.g. true)
    • useDatepicker (e.g. true)
    • minDate (e.g. five weeks ago)
    • maxDate (e.g. 2024-12-31)
  • phone #
    • placeholder
    • pattern
  • rating #
    • colorIdle (e.g. #ddd)
    • colorHover (e.g. gold)
    • colorSelected (e.g. #f70)
    • maxValue (e.g. 5)
      • To manually render a Rating field to use your own styles, your code might look something like this:
{% for i in 1..field.maxValue %}
	<label for="rating-{{ i }}">whatever {{ i }}</label>
	<input type="radio" id="rating-{{ i }}" value="{{ i }}" name="{{ field.handle }}">
{% endfor %}
  • regex #
    • placeholder
    • pattern
    • message
  • website #
    • placeholder

​Methods

  • render() #
    • Use this method to render a predefined, minimal markup html block containing the field's label, input field, instructions and list of errors.
    • Can receive an object of customAttributes as the first and only argument (optional).
    • When using with HTML blocks or Submit buttons, use the hash value provided in property editor in Composer as the handle. Example code would look like:
      • {{ form.get('Ajx7jNxXL').render }}
  • renderLabel() #
    • Use this method to only render the label html field with the field's label inside.
    • The label class can be overwritten via form's custom attributes or the field's custom attributes.
  • renderInput() #
    • Use this method to only render the field's html input field.
    • The class can be overwritten via form's custom attributes or the field's custom attributes.
    • Single Checkbox fieldtype has an additional method: renderSingleInput() to render the checkbox input without an additional hidden input.
  • renderInstructions() #
    • Use this method to only render the field's html instructions field. (Renders only if there are instructions present).
    • The instructions field class can be overwritten via form's custom attributes or the field's custom attributes.
  • renderErrors() #
    • Use this method to only render the error message block. (Renders only if there are errors present).
    • The error list class can be overwritten via form's custom attributes or the field's custom attributes.
  • isValid() # * Returns a boolean value of true if the form has been posted and this field doesn't contain any errors.

​Usage in Templates

​Simple Render

Render the whole field (label, input field, instructions and errors) with a single line:

{{ field.render() }}

​Render Each Part Separately

Render each part of the field separately:

{{ field.renderLabel() }}
{{ field.renderInstructions() }}
{{ field.renderInput() }}
{{ field.renderErrors() }}

​Customize Output

Fully customize the output of your field:

<label data-label class="label">
	{{ field.label }}
	{% if field.instructions %}
		<span class="instructions">{{ field.instructions }}</span>
	{% endif %}
</label>
<input type="text" name="{{ field.handle }}" value="{{ field.valueAsString }}" data-some-value="my_custom_value_here" />
{% if field.errors %}
	{% for errorString in field.errors %}
		<div class="error">{{ errorString }}</div>
	{% endfor %}
{% endif %}

​Override Classes & Values

Render the whole field but override some of the HTML element classes:

{{ field.render({
	class: "freeform-input",
	labelClass: "freeform-label" ~ (field.required ? " freeform-required" : ""),
	errorClass: "freeform-errors",
	instructionsClass: "freeform-instructions",
	instructionsBelowField: true,
	overrideValue: "This is now the new default value",
	inputAttributes: {
		"data-field-id": field.id,
	}
}) }}
Page Feedback