===============
Field reference
===============

Basic inputs
============

.. _field-text:

Text field
----------

.. function:: Pancake::text($name[, $fieldOptions])

    Text ``<input>`` field.
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, text

.. image:: _images/field-text.png

.. _field-textarea:

Textarea
--------

.. function:: Pancake::textarea($name, $cols, $rows[, $fieldOptions])

    ``<textarea>`` field.
    
    :param int cols: HTML ``cols`` attribute.
    :param bool disabled: HTML ``disabled`` attribute.
    :param str name: HTML ``name`` attribute.
    :param bool readonly: HTML ``readonly`` attribute.
    :param int rows: HTML ``rows`` attribute.
    
    .. attribute:: validation
        :noindex:
        
        :class:`HasLinkCount`
        (See :doc:`/topics/security` for more information.)
    
    .. attribute:: paragraphClasses
        :noindex:
        
        field, textarea

.. image:: _images/field-textarea.png

.. _field-checkbox:

Checkbox
--------

.. function:: Pancake::checkbox($name[, $fieldOptions])

    Checkbox ``<input>`` field.
    
    .. attribute:: validation
        :noindex:
        
        :class:`IsCheckbox`
    
    .. attribute:: paragraphClasses
        :noindex:
        
        field, checkbox

.. image:: _images/field-checkbox.png

.. _field-submit:

Submit button
-------------

.. function:: Pancake::submit($name, $value[, $fieldOptions])

    Submit ``<input>`` button.
    
    .. note::
    
        Submit buttons are automatically used as
        :ref:`form identifiers <form-identifiers>`.
    
    .. attribute:: paragraphClasses
        :noindex:
    
        submit

.. image:: _images/field-submit.png

.. _field-file-upload:

File upload
-----------

.. function:: Pancake::fileUpload($name[, $fieldOptions])

    File upload ``<input>`` field.
    
    This field requires the :class:`FileUpload` hook to process file
    uploads after the form is submitted.  You also need to ensure that your
    form's encoding type is set to ``multipart/form-data`` in order to accept
    file uploads (See :doc:`/topics/forms` for more information).
    
    :param bool show_upload_message: Whether or not to show the upload message.
        Defaults to ``true``.
    :param str upload_message: Message to show the user when he/she has already
        uploaded a file.
    :param str upload_to: Directory to which to upload the files.
        Defaults to ``/upload``.
    :param str upload_to_temp: Directory to which to upload the temporary
        files.  Defaults to ``/upload/temp``.
    :param arr valid_types: Valid file MIME types.  Either an array of explicit
        MIME types or a pre-defined :ref:`MIME-type group
        <field-upload-mime-groups>`.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsMIMEType`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, file-upload

.. image:: _images/field-file-upload.png

.. _field-upload-how:

How a file upload works
~~~~~~~~~~~~~~~~~~~~~~~

File uploads work in three steps:

1.  The file is uploaded to a temporary directory in order to preserve the
    uploaded file if the form needs to be re-submitted in order to pass
    validation.  In order to avoid potential naming conflicts, each file name
    is prefixed with a number which increments until the generated file name
    is unique.
    
2.  The temporary file is used to perform any specified validations.

3.  The :class:`FileUpload` hook moves the file out of the temporary
    directory into the permanent directory.

.. _field-upload-mime-groups:

Mime-type groups
~~~~~~~~~~~~~~~~

:func:`fileUpload` includes pre-defined MIME-type groups as a
convenience to refer to a document type without individually specifying a
plethora of MIME types:

audio
  * audio/mpeg

document
  * application/msword
  * application/pdf
  * application/rtf
  * application/vnd.openxmlformats-officedocument.wordprocessingml.document
  * application/vnd.ms-office
  * application/zip
  * text/plain
  * text/rtf

images
  * image/bmp
  * image/gif
  * image/jpeg
  * image/png

video
  * video/quicktime
  * video/mpeg

.. _field-hidden:

Hidden input
------------

.. function:: Pancake::hidden($name[, $fieldOptions])
    
    Hidden ``<input>`` field.  This field automatically sets the options
    :ref:`option-paragraph` and :ref:`option-show_label` to ``false``.

.. _field-input:

Generic input
-------------

.. function:: Pancake::input($name, $type[, $fieldOptions])

    Generic ``<input>`` field.
    
    :param str accept: HTML ``accept`` attribute.
    :param str alt: HTML ``alt`` attribute.
    :param str checked: HTML ``checked`` attribute.
    :param str disabled: HTML ``disabled`` attribute.
    :param str maxlength: HTML ``maxlength`` attribute.
    :param str readonly: HTML ``readonly`` attribute.
    :param str size: HTML ``size`` attribute.
    :param str src: HTML ``src`` attribute.
    :param str type: HTML ``type`` attribute.
    :param str usemap: HTML ``usemap`` attribute.
    :param str value: HTML ``value`` attribute.

    .. attribute:: paragraphClasses
        :noindex:

        field

Dates
=====

.. _field-date-text:

Date text fields
----------------

.. function:: Pancake::date($name[, $fieldOptions])

    Three text ``<input>`` boxes for the day, month, and year.
    
    :param str container: HTML tag for the group container. 
        Defaults to ``div``.
    :param str date_format: Date format for the formatted value.
        Defaults to ``l, j F Y``.
    :param str label_element: HTML tag for the group label.
        Defaults to ``h3``.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsDate`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, date

.. image:: _images/field-date-text.png

.. _field-date-selects:

Date select drop-downs
----------------------

.. function:: Pancake::dateDropDowns($name[, $fieldOptions])

    Three ``<select>`` drop downs for the day, month, and year.
    
    :param str container: HTML tag for the group container.
        Defaults to ``div``.
    :param str date_format: Date format for the formatted value.
        Defaults to ``l, j F Y``.
    :param str label_element: HTML tag for the group label.
        Defaults to ``h3``.
    :param str year_end: End year, run through
        `strtotime() <http://php.net/manual/en/function.strtotime.php>`_.
        Defaults to ``+5 years``.
    :param str year_start: Start year, run through
        `strtotime() <http://php.net/manual/en/function.strtotime.php>`_.
        Defaults to ``-5 years``.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsDate`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, date, date-drop-downs

.. image:: _images/field-date-selects.png

.. _field-date-calendar:

Date calendar
-------------

.. function:: Pancake::dateCalendar($name[, $fieldOptions])

    Date calendar ``<input>`` field.
    
    .. note::
    
        The automatic pop-up calendar requires Pancake's
        :doc:`/topics/static-media`.
    
    :param str date_format: Date format for the formatted value.
        Defaults to ``l, j F Y``.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsDate`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, date, text, calendar

.. image:: _images/field-date-calendar.png

.. _field-date-estimation:

Date estimation
---------------

.. function:: Pancake::dateEstimation($name[, $fieldOptions])

    Two ``<select>`` drop downs for semester and year.
    
    :param str container: HTML tag for the group container.
        Defaults to ``div``.
    :param str label_element: HTML tag for the group label.
        Defaults to ``h3``.
    :param str year_end: End year, run through
        `strtotime() <http://php.net/manual/en/function.strtotime.php>`_. 
        Defaults to ``+5 years``.
    :param str year_start: Start year, run through
        `strtotime() <http://php.net/manual/en/function.strtotime.php>`_.
        Defaults to ``-5 years``.
    
    .. attribute:: validation
        :noindex:
    
        :class:`MatchesPattern` for the pattern ``#([A-Za-z]+) (\d{4})#``.
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, date, date-drop-downs

.. image:: _images/field-date-estimation.png

.. _list-fields:

Lists
=====

.. _field-list-checkboxes:

Checkbox list
-------------

.. function:: Pancake::checkboxList($name, $options[, $fieldOptions])

    Checkbox ``<input>`` list field.
    
    :param str container: HTML tag for the group container.
        Defaults to ``div``.
    :param str label_element: HTML tag for the group label.
        Defaults to ``h3``.
    :param arr options: List of possible options.
        The string ``other`` becomes a text ``<input>`` field.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsOneOf`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, list, checkbox-list

.. image:: _images/field-list-checkboxes.png

.. _field-list-radios:

Radio-button list
-----------------

.. function:: Pancake::radioList($name, $options[, $fieldOptions])

    Radio button ``<input>`` list field.
    
    :param str container: HTML tag for the group container.
        Defaults to ``div``.
    :param str label_element: HTML tag for the group label.
        Defaults to ``h3``.
    :param arr options: List of possible options.
        The string ``other`` becomes a text ``<input>`` field.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsOneOf`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, list, radio-list

.. image:: _images/field-list-radios.png

.. _field-select:

Select drop-downs
-----------------

.. function:: Pancake::select($name, $options[, $fieldOptions])

    Drop-down ``<select>`` box field.
    
    :param str disabled: HTML ``disabled`` attribute.
    :param bool include_blank: Whether or not to include a blank ``<option>``.
        Defaults to ``true``.
    :param str multiple: HTML ``multiple`` attribute.
    :param arr options: List of possible options.
    :param str size: HTML ``size`` attribute.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsOneOf`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, select

.. image:: _images/field-select.png

.. _field-list-ranking:

Ranking list
------------

.. function:: Pancake::ranking($name, $options[, $fieldOptions])

    List of rank-able text ``<input>`` fields.
    
    :param str container: HTML tag for the group container.
        Defaults to ``div``.
    :param str label_element: HTML tag for the group label.
        Defaults to ``h3``.
    :param arr options: List of possible options.
    :param int rank_up_to: Number up to which the user must rank the values.
        Defaults to the total number of options.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsRanked`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, list, ranking

.. image:: _images/field-list-ranking.png

Specialised inputs
==================

.. _field-email:

Email address
-------------

.. function:: Pancake::email($name[, $fieldOptions])

    Email address ``<input>`` field.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsEmail`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, text, email

.. image:: _images/field-email.png

.. _field-phone-number:

Phone number
------------

.. function:: Pancake::phone($name[, $fieldOptions])

    Phone number ``<input>`` field.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsPhoneNumber`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, text, phone

.. image:: _images/field-phone-number.png

.. _field-postal-code:

Postal code
-----------

.. function:: Pancake::postalCode($name[, $fieldOptions])

    US and Canadian postal code ``<input>`` field.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsPostalCode`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, text, postal-code

.. image:: _images/field-postal-code.png

.. _field-states:

US state
--------

.. function:: Pancake::states($name[, $fieldOptions])

    US states and Canadian provinces ``<select>`` drop-down field.
    
    :param bool include_blank: Whether or not to include a blank ``<option>``.
        Defaults to ``true``.
    
    .. attribute:: validation
        :noindex:
    
        :class:`IsOneOf`
    
    .. attribute:: paragraphClasses
        :noindex:
    
        field, select, states

.. image:: _images/field-states.png