Form fields

A form field is an input element—such as a text field, a checkbox, or a submit button—and its label. This section covers how to use form fields.

Field syntax

To add a field to your form, call the appropriate method on your Pancake form instance. Each field must have a unique name, which is always the first argument of the method call. Below is an example in which two text fields are added to a form:

<?= $form->start() ?>
    <fieldset>
        <legend>Name</legend>

        <?= $form->text('first_name') ?>
        <?= $form->text('last_name') ?>
    </fieldset>
<?= $form->end() ?>

Some fields have additional required arguments, such as a select drop-down box, which requires an array of options as the second argument:

<?= $form->start() ?>
    <?= $form->select('numbers', array('yksi', 'kaksi', 'kolme')) ?>
<?= $form->end() ?>

Beyond the required arguments, each field has optional arguments as well. These optional arguments—which comprise validation, HTML attributes, and properties—are passed as the last argument of the method call as an associative array, wherein the key is the name of the option:

<?= $form->start() ?>
    <?= $form->select('numbers', array('yksi', 'kaksi', 'kolme'), array(
        'label' => 'Number (in Finnish)',
        'required' => false
    )) ?>
<?= $form->end() ?>

Field labels are automatically generated using the field’s name. The field label can be manually set by the label property. Below are some examples of labels generated from field names:

Field name	Label
first_name	First Name
last_name	Last Name
email	Email
question_or_concern	Question or Concern

Validation

By default, each field is required, i.e. must have a value. The validation option sets the additional validators that apply to a form field. To assign a single validator to a form field, pass the name of the validator as a string:

<?= $form->start() ?>
    <?= $form->text('your_website', array(
        'validation' => 'IsURL'
    )) ?>
<?= $form->end() ?>

When a form is submitted, each form field is passed through each validator which is assigned to it. If any form field does not validate, the user is prompted to correct the errors. An overall validation message is displayed at the top of the form and individual error messages are displayed inline in each form field’s label:

You can assign multiple validators to a form field by passing the names of the validators as an array of strings:

<?= $form->start() ?>
    <?= $form->text('your_website', array(
        'validation' => array('IsURL', 'IsRequired')
    )) ?>
<?= $form->end() ?>

Note

It is unnecessary to assign the IsRequired validator to a field. The required field property handles this assignment automatically.

If a validator has options, use an array with the validator’s name as the first element and the options as separate elements succeeding it. In order to avoid interpreting the array as multiple validators, Pancake requires that you nest the options-filled array within an array, as if you were assigning multiple validators:

<?= $form->start() ?>
    <?= $form->text('number', array(
        'validation' => array(array('IsBetween', 1, 10))
    )) ?>
<?= $form->end() ?>

Likewise, you can assign multiple validators to a form field which each have their own options:

<?= $form->start() ?>
    <?= $form->text('number', array(
        'validation' => array(
            array('IsBetween', 1, 10),
            array('IsOneOf', array(1, 3, 5, 7, 9))
        )
    )) ?>
<?= $form->end() ?>

Whilst each validator generates its own error message, you can override this error message by passing the option error to the validator:

<?= $form->start() ?>
    <?= $form->text('number', array(
        'validation' => array(
            array('IsBetween', 1, 10),
            array('IsOneOf', array(1, 3, 5, 7, 9), 'error' => 'Please enter an odd number.')
        )
    )) ?>
<?= $form->end() ?>

Creating your own validators

Custom validators are simple PHP functions which accept an input and return true, if the validation is successful, or an error message, if the validation fails. Below is an example of a custom validation function:

<?php
/**
 * Validates that the applicant selected three shifts
 *
 * @param  array $selected_shifts Shifts selected by the user
 * @return boolean|string
 */
function validate_shifts($selected_shifts)
{
    // Make sure the input is an array
    if (!is_array($selected_shifts))
    {
        $selected_shifts = array($selected_shifts);
    }

    // Check that the minimum number of shifts has been selected
    if (count($selected_shifts) < 3)
    {
        return 'You must be available to work at least 3 shifts.';
    }

    return true;
}
?>

These custom validators are applied to form fields just like Pancake’s built-in validators. You should use a fully-qualified name to ensure that the name is correctly resolved.

<?= $form->start() ?>
    <?= $form->checkboxList('shift_availability', array(
        'Monday',
        'Tuesday',
        'Wednesday',
        'Thursday',
        'Friday'
    ), array(
        'label' => 'Which shifts are you available to work?',
        'validation' => array(array('\validate_shifts', $posting))
    )) ?>
<?= $form->end() ?>

List fields

List fields are fields that contain a series of options. List fields must be passed an array of possible options. If a particular option is other, that option is rendered as a free-form text box. Below is an example of a radio-button list field:

<?= $form->start() ?>
    <?= $form->radioList('native_language', array(
        'English',
        'Swedish',
        'Finnish',
        'other'
    )) ?>
<?= $form->end() ?>

You can specify field options for a list-field option by replacing the simple string value with an array that matches the format of a form-field method call.

<?= $form->start() ?>
    <?= $form->radioList('native_language', array(
        'English',
        array('swedish', array('label' => 'Svenska (Swedish)')),
        array('finnish', array('label' => 'Suomi (Finnish)')),
        'other'
    )) ?>
<?= $form->end() ?>