========
Tutorial
========

Install Pancake PHP
===================

Follow these steps to install Pancake PHP:

1. `Download Pancake PHP from Bitbucket.
   <http://bitbucket.org/ethanpoole/pancake>`_
2. Unzip the downloaded archive.
3. Upload the ``Pancake`` directory to a location on your PHP
   include path.

If you want to utilise Pancake's :doc:`included CSS and JavaScript files
<topics/static-media>`, you need to perform the additional following two steps:

4. Copy or symlink the ``Pancake/Resources/css`` and ``Pancake/Resources/js``
   directories to public file paths.
5. Modify the settings in ``Pancake/Settings/Other.php`` as appropriate.

Create the form
===============

First, include Pancake in your PHP file.  Pancake uses a class autoloader, so
you only need to include the ``Pancake/Pancake.php`` file.

.. code-block:: php

    <?php
    include_once 'Pancake/Pancake.php';
    ?>

Next, create an instance of ``Pancake\Pancake``.  You can name the variable
whatever you would like, but ``$form`` is the convention.

.. code-block:: php

    <?php
    $form = new Pancake\Pancake;
    ?>

A Pancake form is enclosed in calls to the ``Pancake::start()`` and
``Pancake::end()`` methods:

.. code-block:: php

    <?= $form->start() ?>
        // Form contents...
    <?= $form->end() ?>

After having completed these three steps, you should have the following:

.. code-block:: php

    <?php
    include_once 'Pancake/Pancake.php';
    $form = new Pancake\Pancake;
    ?>
    
    <?= $form->start() ?>
        // Form contents...
    <?= $form->end() ?>

Add fields to the form
======================

To add a :doc:`field <topics/form-fields>` 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.

.. code-block:: php

    <?php
    include_once 'Pancake/Pancake.php';
    $form = new Pancake\Pancake;
    ?>
    
    <?= $form->start() ?>
        <fieldset>
            <legend>Register</legend>
            
            <?= $form->text('first_name') ?>
            <?= $form->text('middle_name', array(
                'required' => false
            )) ?>
            <?= $form->text('last_name') ?>
            
            <?= $form->email('email_address') ?>
        </fieldset>
        
        <?= $form->submit('submit', 'Apply') ?>
    <?= $form->end() ?>

.. image:: _images/tutorial-1.png

Process the form
================

You can specify :doc:`hooks </topics/hooks>` that process the form after it
passes validation.  These hooks can be used to email the submitted form data,
send a confirmation email, and much more.

.. code-block:: php
    
    <?php
    include_once 'Pancake/Pancake.php';
    $form = new Pancake\Pancake;
    
    $form->addHook(
        'after',
        'EmailForm',
        array(
            'to' => 'example@example.com',
            'from' => 'email'
        )
    );
    ?>

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

            <?= $form->text('first_name') ?>
            <?= $form->text('middle_name', array(
                'required' => false
            )) ?>
            <?= $form->text('last_name') ?>

            <?= $form->email('email_address') ?>
        </fieldset>

        <?= $form->submit('submit', 'Apply') ?>
    <?= $form->end() ?>