===========
Form fields
===========

A form field is an input element---such as a :ref:`text field <field-text>`, a
:ref:`checkbox <field-checkbox>`, or a :ref:`submit button <field-submit>`---and
its label.  This section covers how to use form fields.

Field syntax
------------

To add a field to your form, call :doc:`the appropriate method </references/form-fields>`
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:

.. code-block:: php

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

.. image:: _images/form-fields-example-1.png

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

.. code-block:: php

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

.. image:: _images/form-fields-example-2.png

Beyond the required arguments, each field has optional arguments as well.
These :ref:`optional arguments <field-options>`---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:

.. code-block:: php

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

.. image:: _images/form-fields-example-3.png

Field labels are automatically generated using the field's name.  The field
label can be manually set by the :ref:`option-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:

Validation
----------

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

.. code-block:: php

    <?= $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:

.. image:: _images/form-fields-validation-errors.png

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

.. code-block:: php

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

.. note::
    It is unnecessary to assign the :class:`IsRequired` validator to a
    field.  The :ref:`option-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:

.. code-block:: php

    <?= $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:

.. code-block:: php

    <?= $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:

.. code-block:: php

    <?= $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:

.. code-block:: php

    <?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
<http://php.net/manual/en/language.namespaces.rules.php>`_ to ensure that the
name is correctly resolved.

.. code-block:: php

    <?= $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:

.. code-block:: php

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

.. image:: _images/form-fields-list-1.png

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.

.. code-block:: php

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

.. image:: _images/form-fields-list-2.png