Field options

Attributes

Attributes correspond directly to the HTML attributes of the form-field input HTML element, i.e. <input>, <textarea>, <select>. The following attributes are available to every form field:

class

class

HTML class attribute of the form-field input.

id

id

Pancake automatically generates the HTML id attribute of the form-field input based on the field’s name. You can override the generated id using this attribute.

name

name

Pancake automatically uses the field’s name as the HTML name attribute of the form-field input element. You can override the name using this attribute.

Properties

Properties are settings for fields that are not HTML attributes, such as whether to hide the label, show the help text, require the field, etc.

accessible_text

accessible_text

Instructional text intended for visually-impaired users which is placed within the <label>. This property is useful if your form uses JavaScript to show and hide fields which a visually-impaired user would not otherwise notice. Setting this property automatically adds the paragraph class accessible-text.

For example, the following Pancake form field:

<?= $form->text('event_contact', array(
    'accessible_text' => 'This field is only necessary if it\'s
                          different from the primary contact.'
)) ?>

results in the following HTML output:

<p class="accessible-text field text">
    <label for="f_event_contact">
        Event Contact
        <span class="accessible">
            This field is only necessary if it's different from the primary contact.
        </span>
    </label>
    <input id="f_event_contact" name="event_contact" type="text" />
</p>

after

after

Arbitrary string value that is displayed after the field-form input.

before

before

Arbitrary string value that is displayed before the <label>.

container

container

HTML tag that encompasses the entire form field. Do not include opening and closing angle brackets. Defaults to p.

Note

This property is used internally by list fields to change the default p to a div, which is more suitable for a group of form fields that each have their own container element.

help_text

help_text

Instructional text which is placed within the <label>, but after the label text. Setting this property automatically adds the paragraph class help-text.

label

label

Explicit label text. The label text is otherwise generated based on the form field’s name.

label_element

label_element

HTML tag that encompasses the label text. If the value is not label, the for attribute will be removed. Do not include opening and closing brackets. Defaults to label.

Note

This property is used internally by list fields to change the default label to an h3, which is more suitable for a group of form fields that each have their own <label>.

label_first

label_first

Whether or not the <label> should precede the form-field input. If false, the <label> succeeds the form-field input. Defaults to true.

Note

This property is used internally by checkboxes to place the <label> after the checkbox.

label_short

label_short

Truncated label text which is used in validation messages. This property is useful for essay questions which may be abnormally long in the top-of-the-form validation message.

paragraph

paragraph

Whether or not to encompass the field in a container element, i.e. a paragraph. Defaults to true.

paragraph_classes

paragraph_classes

Pancake automatically adds classes to your form-field container which correspond to the type of form field and to the form field’s other options. Additionally, any form field with validation errors will automatically receive the class error. You can further add custom classes to the form-field container using this property.

See Field reference for details about automatically assigned paragraph classes based on the form-field type.

required

required

Whether or not the field is required. If false, the field will be marked as optional in the <label>. Optional fields will automatically receive the paragraph class optional. Defaults to true.

This message will be hidden if required is set to false:

required_if

required_if

This option allows you to set the requirement of a field based on the value of another field. The property value should be an array wherein the first entry is the name of the dependent field and the second entry is the target value.

<?= $form->text('foo', array(
    'required_if' => array('conditional', 'value')
)) ?>

show_errors

show_errors

Whether or not to show the validation errors in the field’s <label>. Defaults to true.

show_field

show_field

Whether or not to show the form-field input element. Defaults to true.

show_if_optional

show_if_optional

Whether or not to show if the field is optional in the <label>. Defaults to true.

show_label

show_label

Whether or not to show the <label>. Defaults to true.

validation

validation

Validators to apply to the form field. See Validation for more information about field validation.