Forms
=====
Phalcon\\Forms is a component that aid the developer in the creation and maintenance of forms in web applications.

The following example shows its basic usage:

.. code-block:: php

    <?php

    use Phalcon\Forms\Form,
        Phalcon\Forms\Element\Text,
        Phalcon\Forms\Element\Select;

    $form = new Form();

    $form->add(new Text("name"));

    $form->add(new Text("telephone"));

    $form->add(new Select("telephoneType", array(
        'H' => 'Home',
        'C' => 'Cell'
    )));

Forms can be rendered based on the form definition:

.. code-block:: html+php

    <h1>Contacts</h1>

    <form method="post">

        <p>
            <label>Name</label>
            <?php echo $form->render("name") ?>
        </p>

        <p>
            <label>Telephone</label>
            <?php echo $form->render("telephone") ?>
        </p>

        <p>
            <label>Type</label>
            <?php echo $form->render("telephoneType") ?>
        </p>

        <p>
            <input type="submit" value="Save" />
        </p>

    </form>

Each element in the form can be rendered as required by the developer. Internally,
:doc:`Phalcon\\Tag <../api/Phalcon_Tag>` is used to produce the right HTML for each element,
you can pass additional html attributes as second parameter for render:

.. code-block:: html+php

    <p>
        <label>Name</label>
        <?php echo $form->render("name", array('maxlength' => 30, 'placeholder' => 'Type your name')) ?>
    </p>

HTML Attributes also can be set in the element's definition:

.. code-block:: php

    <?php

    $form->add(new Text("name", array(
        'maxlength' => 30,
        'placeholder' => 'Type your name'
    )));

Initializing forms
------------------
As seen before, forms can be initialized outside the form class by adding elements to it. You can re-use code or organize your form
classes implementing the form in a separated file:

.. code-block:: php

    <?php

    use Phalcon\Forms\Form,
        Phalcon\Forms\Element\Text,
        Phalcon\Forms\Element\Select;

    class ContactForm extends Form
    {
        public function initialize()
        {
            $this->add(new Text("name"));

            $this->add(new Text("telephone"));

            $this->add(new Select("telephoneType", TelephoneTypes::find(), array(
                'using' => array('id', 'name')
            )));
        }
    }

:doc:`Phalcon\\Forms\\Form <../api/Phalcon_Forms_Form>` extends :doc:`Phalcon\\DI\\Injectable <../api/Phalcon_DI_Injectable>`
so you have access to the application services if needed:

.. code-block:: php

    <?php

    use Phalcon\Forms\Form,
        Phalcon\Forms\Element\Text,
        Phalcon\Forms\Element\Hidden;

    class ContactForm extends Form
    {

        /**
         * This method returns the default value for field 'csrf'
         */
        public function getCsrf()
        {
            return $this->security->getToken();
        }

        public function initialize()
        {

            //Set the same form as entity
            $this->setEntity($this);

            //Add a text element to capture the 'email'
            $this->add(new Text("email"));

            //Add a text element to put a hidden csrf
            $this->add(new Hidden("csrf"));
        }
    }

The associated entity added to the form in the initialization and custom user options are passed to the form constructor:

.. code-block:: php

    <?php

    use Phalcon\Forms\Form,
        Phalcon\Forms\Element\Text,
        Phalcon\Forms\Element\Hidden;

    class UsersForm extends Form
    {
        /**
         * Forms initializer
         *
         * @param Users $user
         * @param array $options
         */
        public function initialize($user, $options)
        {

            if ($options['edit']) {
                $this->add(new Hidden('id'));
            } else {
                $this->add(new Text('id'));
            }

            $this->add(new Text('name'));
        }
    }

In the form's instantiation you must use:

.. code-block:: php

    <?php

    $form = new UsersForm(new Users(), array('edit' => true));

Validation
----------
Phalcon forms are integrated with the :doc:`validation <validation>` component to offer instant validation. Built-in or
custom validators could be set to each element:

.. code-block:: php

    <?php

    use Phalcon\Forms\Element\Text,
        Phalcon\Validation\Validator\PresenceOf,
        Phalcon\Validation\Validator\StringLength;

    $name = new Text("name");

    $name->addValidator(new PresenceOf(array(
        'message' => 'The name is required'
    )));

    $name->addValidator(new StringLength(array(
        'min' => 10,
        'messageMinimum' => 'The name is too short'
    )));

    $form->add($name);

Then you can validate the form according to the input entered by the user:

.. code-block:: php

    <?php

    if (!$form->isValid($_POST)) {
        foreach ($form->getMessages() as $message) {
            echo $message, '<br>';
        }
    }

Validators are executed in the same order as they were registered.

By default messages generated by all the elements in the form are joined so they can be traversed using a single foreach,
you can change this behavior to get the messages separated by the field:

.. code-block:: php

    <?php

    foreach ($form->getMessages(false) as $attribute => $messages) {
        echo 'Messages generated by ', $attribute, ':', "\n";
        foreach ($messages as $message) {
            echo $message, '<br>';
        }
    }

Or get specific messages for an element:

.. code-block:: php

    <?php

    foreach ($form->getMessagesFor('name') as $message) {
        echo $message, '<br>';
    }

Filtering
---------
A form is also able to filter data before be validated, you can set filters in each element:



Setting User Options
--------------------
Forms + Entities
----------------
An entity such as a model/collection/plain instance or just a plain PHP class can be linked to the form in order to set default values
in the form's elements or assign the values from the form to the entity easily:

.. code-block:: php

    <?php

    $robot = Robots::findFirst();

    $form = new Form($robot);

    $form->add(new Text("name"));

    $form->add(new Text("year"));

Once the form is rendered if there is no default values assigned to the elements it will use the ones provided by the entiy:

.. code-block:: html+php

    <?php echo $form->render('name') ?>

You can validate the form and assign the values from the user input in the following way:

.. code-block:: php

    <?php

    $form->bind($_POST, $robot);

    //Check if the form is valid
    if ($form->isValid()) {

        //Save the entity
        $robot->save();
    }

Setting up a plain class as entity also is possible:

.. code-block:: php

    <?php

    class Preferences
    {

        public $timezone = 'Europe/Amsterdam';

        public $receiveEmails = 'No';

    }

Using this class as entity, allows the form to take the default values from it:

.. code-block:: php

    <?php

    $form = new Form(new Preferences());

    $form->add(new Select("timezone", array(
        'America/New_York' => 'New York',
        'Europe/Amsterdam' => 'Amsterdam',
        'America/Sao_Paulo' => 'Sao Paulo',
        'Asia/Tokio' => 'Tokio',
    )));

    $form->add(new Select("receiveEmails", array(
        'Yes' => 'Yes, please!',
        'No' => 'No, thanks'
    )));

Entities can implement getters, which have more precedence than public propierties, these methods
give you more free to produce values:

.. code-block:: php

    <?php

    class Preferences
    {

        public $timezone;

        public $receiveEmails;

        public function getTimezone()
        {
            return 'Europe/Amsterdam';
        }

        public function getTimezone()
        {
            return 'No';
        }

    }

Form Elements
-------------
Phalcon provides a set of built-in elements to use in your forms, all these elements are located in the Phalcon\\Forms\\Element namespace:

+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Name         | Description                                                                                                                                                      | Example                                                           |
+==============+==================================================================================================================================================================+===================================================================+
| Text         | Generate INPUT[type=text] elements                                                                                                                               | :doc:`Example <../api/Phalcon_Forms_Element_Text>`                |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Password     | Generate INPUT[type=password] elements                                                                                                                           | :doc:`Example <../api/Phalcon_Forms_Element_Password>`            |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Select       | Generate SELECT tag (combo lists) elements based on choices                                                                                                      | :doc:`Example <../api/Phalcon_Forms_Element_Select>`              |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Check        | Generate INPUT[type=check] elements                                                                                                                              | :doc:`Example <../api/Phalcon_Forms_Element_Check>`               |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Textarea     | Generate TEXTAREA elements                                                                                                                                       | :doc:`Example <../api/Phalcon_Forms_Element_TextArea>`            |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Hidden       | Generate INPUT[type=hidden] elements                                                                                                                             | :doc:`Example <../api/Phalcon_Forms_Element_Hidden>`              |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| File         | Generate INPUT[type=file] elements                                                                                                                               | :doc:`Example <../api/Phalcon_Forms_Element_File>`                |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Date         | Generate INPUT[type=date] elements                                                                                                                               | :doc:`Example <../api/Phalcon_Forms_Element_Date>`                |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Numeric      | Generate INPUT[type=number] elements                                                                                                                             | :doc:`Example <../api/Phalcon_Forms_Element_Numeric>`             |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| Submit       | Generate INPUT[type=submit] elements                                                                                                                             | :doc:`Example <../api/Phalcon_Forms_Element_Submit>`              |
+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+

Event Callbacks
---------------
Whenever forms are implemented as classes, the callbacks: beforeValidation and afterValidation can be implemented
in the form's class to perform pre-validations and post-validations:

.. code-block:: html+php

    <?php

    class ContactForm extends Phalcon\Mvc\Form
    {
        public function beforeValidation()
        {

        }
    }

Rendering Forms
---------------
You can render the form with total flexibility, the following example shows how to render each element using an standard procedure:

.. code-block:: html+php

    <?php

    <form method="post">
        <?php
            //Traverse the form
            foreach ($form as $element) {

                //Get any generated messages for the current element
                $messages = $form->getMessagesFor($element->getName());

                if (count($messages)) {
                    //Print each element
                    echo '<div class="messages">';
                    foreach ($messages as $message) {
                        echo $message;
                    }
                    echo '</div>';
                }

                echo '<p>';
                echo '<label for="', $element->getName(), '">', $element->getLabel(), '</label>';
                echo $element;
                echo '</p>';

            }
        ?>
        <input type="submit" value="Send"/>
    </form>

Or reuse the logic in your form class:

.. code-block:: php

    <?php

    class ContactForm extends Phalcon\Forms\Form
    {
        public function initialize()
        {
            //...
        }

        public function renderDecorated($name)
        {
            $element = $this->get($name);

            //Get any generated messages for the current element
            $messages = $this->getMessagesFor($element->getName());

            if (count($messages)) {
                //Print each element
                echo '<div class="messages">';
                foreach ($messages as $message) {
                    echo $this->flash->error($message);
                }
                echo '</div>';
            }

            echo '<p>';
            echo '<label for="', $element->getName(), '">', $element->getLabel(), '</label>';
            echo $element;
            echo '</p>';
        }

    }

In the view:

.. code-block:: php

    <?php

    echo $element->renderDecorated('name');

    echo $element->renderDecorated('telephone');

Creating Form Elements
----------------------
In addition to the form elements provided by Phalcon you can create your own custom elements:

.. code-block:: php

    <?php

    use Phalcon\Forms\Element;

    class MyElement extends Element
    {
        public function render($attributes=null)
        {
            $html = //... produce some html
            return $html;
        }
    }

Forms Manager
-------------
This component provides a forms manager that can be used by the developer to register forms and access them via the service locator:

.. code-block:: php

    <?php

    $di['forms'] = function() {
        return new Phalcon\Forms\Manager();
    };

Forms are added to the forms manager and referenced by a unique name:

.. code-block:: php

    <?php

    $this->forms->set('login', new LoginForm());

Using the unique name, forms can be accesed in any part of the application:

.. code-block:: php

    <?php

    echo $this->forms->get('login')->render();

External Resources
------------------
* `Vökuró <http://vokuro.phalconphp.com>`_, is a sample application that uses the forms builder to create and manage forms, [`Github <https://github.com/phalcon/vokuro>`_]