.. _field-options:

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

.. _option-class:

``class``
---------

.. attribute:: class

    HTML ``class`` attribute of the form-field input.

.. _option-id:

``id``
------

.. attribute:: 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.

.. _option-name:

``name``
--------

.. attribute:: 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.

.. _option-accessible_text:

``accessible_text``
-------------------

.. attribute:: 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:

.. code-block:: php

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

.. code-block:: html

    <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>	

.. _option-after:

``after``
---------

.. attribute:: after

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

.. _option-before:

``before``
----------

.. attribute:: before

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

.. _option-container:

``container``
-------------

.. attribute:: 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 :ref:`list fields <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.

.. _option-help_text:

``help_text``
-------------

.. attribute:: 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``.

.. image:: _images/option-help-text.png

.. _option-label:

``label``
---------

.. attribute:: label

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

.. _option-label_element:

``label_element``
-----------------

.. attribute:: 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 :ref:`list fields <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>``.

.. _option-label_first:

``label_first``
---------------

.. attribute:: 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 :ref:`checkboxes <field-checkbox>`
        to place the ``<label>`` after the checkbox.

.. _option-label_short:

``label_short``
---------------

.. attribute:: 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.

.. _option-paragraph:

``paragraph``
-------------

.. attribute:: paragraph

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

.. _option-paragraph_classes:

``paragraph_classes``
---------------------

.. attribute:: 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 :doc:`/references/form-fields` for details about automatically assigned
    paragraph classes based on the form-field type.

.. _option-required:

``required``
------------

.. attribute:: 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``:

.. image:: _images/option-required.png

.. _option-required-if:

``required_if``
---------------

.. attribute:: 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.
    
    .. code-block:: php
    
        <?= $form->text('foo', array(
            'required_if' => array('conditional', 'value')
        )) ?>

.. _option-show_errors:

``show_errors``
---------------

.. attribute:: show_errors

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

.. _option-show_field:

``show_field``
--------------

.. attribute:: show_field

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

.. _option-show_if_optional:

``show_if_optional``
--------------------

.. attribute:: show_if_optional

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

.. _option-show_label:

``show_label``
--------------

.. attribute:: show_label

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

.. _option-validation:

``validation``
--------------

.. attribute:: validation

    Validators to apply to the form field.  See :ref:`validation` for more
    information about field validation.