Form Field Tag HTML Objects

When you are working with form fields in your form templates you will be working with a HTML Object.

The purpose of the HTML Object is to allow you to add or change the attributes for the field tag before outputting the form field tag. Instead of having to manually build out the form field tag just to set a custom class value you can set the attribute value and then simply output the form field tag. This helps with readability and is often easier to write.

Instead of doing this:

<input type="{{ field.type }}" class="CustomClass" value="{{ field.type}" id="{{ field.id }}">

now you can set the class value and then simply output the code:

{% set field.class = 'form-class' %}
{{ field.tag }} 

Available form field tag attributes

Typically the following form field tag attributes are available for you to set or change values:

{{ field.class }}
{{ field.cols }}
{{ field.id }}
{{ field.name }}
{{ field.placeholder }}
{{ field.rows }}
{{ field.size }}
{{ field.type }}
{{ field.value }}

You can also set any valid HTML attribute on the form field tag such as 'data' attributes.

See HTML Objects for more information about setting attribute values.

Additional field data

There is additional data that is available in the field tag that you can output in your templates, but they are not attributes so they are not manipulated in the same way.

{{ field.description }}
{{ field.label }}
{{ field.text }} (used only with HTML field types like 'Section Heading' or 'Field Group')

You can set the value for these, but you can't do things like {{ field.description.prepend('value') }}. 'description' is not an attribute so it doesn't have the 'prepend', 'set' or 'append' methods. It's just a string value.

You can do:

{% set field.description = 'Field description' %}
{% field.label = 'New field label' %}
or
{% set field.description = field.description ~ ' More descriptive text here' %}
{% set field.label = field.label ~ ' more label text' %}

Field option tags

Select menu, radio button and checkbox form fields have an options array that holds each select menu option, radio button and checkbox tag, respectively.

Each of the option tags is a HTML Object. Their attributes can be manipulated just like form field tag attributes can. For example, while looping through the options for a multi-checkbox field you could set a class name that is different from the class name set when the field was created.

{% for option in field.options %}
    {{ option.class.append('my-class') }}
    {{ option.tag }}
{% endfor %}

Note that you can use {{ option.tag }} to output the full option tag with it's label. Or you can use {{ option.tagNoLabel }} to get just the option tag without the label. This only applies to checkboxes and radio buttons.

{{ option.tag }}
outputs:
<label><input type="checkbox" value="val"> Field Label</label>

{{ option.tagNoLabel }}
outputs:
<input type="checkbox" value="val">

{{ option.label }} would just output the label text

 Field configuration data

If the field is a radio button or checkbox then a configuration value is available to set whether or not the radio buttons or checkboxes will be separated by a new line or by a space.

{
    'config': {
        'separator': 'newline'
    }
}

The field.config.separator value can be set to one of the following values:

  • newline
  • space

You can also set custom configuration values to use in your template.

{% set field.config.myValue = 'custom value' %}

You can then use that custom value like this:

{% if config.myValue == 'custom value' %}
    // Something here
{% endif %}

None of the field.config values will be outputted as the field tag attributes.

Changing field type

If desired you can change the field type in your template. For example, if the original field type is a text box and you want to change it to a text area you could do the following:

{% set field.type = 'textarea' %}
{{ field.tag }}

That would change the field type to a text area and then when the tag is outputted it will be a <textarea> tag.

You can also change a field to a select menu, checkbox or radio buttons. First change the field type:

{% set field.type = 'select' %}

Then set the field options if necessary. The field options need to be an object hash with a key and a value. The key is the actual value that is submitted for the select menu and the value is the option label text.

{% set field.options = {'value1': 'Value 1', 'value2': 'Value 2'} %}

Note, the hash key and value could be the same. 

{% set field.options = {'Value 1': 'Value 1', 'Value 2': 'Value 2'} %}

Set a default value for select menus

Sometimes with a select menu field <select> you want the default option to be something like "-- Select One --" with an empty value. This would allow the user to skip answering that field and not have a value pre-selected.

You could accomplish this by manually adding this value to the field options. Or, you could use the setFirstOption method to add a default first option in your template code.

{% do field.setFirstOption('-- Select One --') %}

While it's intended that this method would be used to add a default option with an empty value, you can use it to prepend values to the select menu options by passing a value to the second parameter.

{% do field.setFirstOption('My Option Label', 'my option value') %}

If the value of the first existing option matches the passed value then the first option will be replaced with the new information. This applies even if you added a field option with an empty value. 

Set the selected value(s) for checkboxes, radio buttons or select menus

You can manually select which value or values are initially selected for checkboxes, radio buttons, and select menus.

Option 1 - set the value that should be selected

{% set field.value = 'value-to-select' %}

If your field is a Multi-Checkbox field then you can set multiple values to be selected.

{% set field.value = ['value', 'another-value', 'yet-another-value'] %}

Option 2 - set the checked or selected attribute

If your field is a single checkbox then you can also simply set it to be checked.

{% set field.checked = true %}

Likewise, you could set it to not be checked.

{% set field.checked = false %}

If your field type is a Multi-Checkbox then if you set the field to be checked then all of the checkboxes will be checked.

{% set field.selected = true %}

If your field type is a Multi-Select then if you set the field to be selected then all the options will be selected.

Option 3 - set an individual option to be checked or selected

Checkboxes

{% for option in field.options %}
    {% if option.value == 'my-value' %}
        {% set option.checked = true %}
    {% endif %}
{% endfor %}

Select Menus

{% for option in field.options %}
    {% if option.value == 'my-value' %}
        {% set option.selected = true %}
    {% endif %}
{% endfor %}