=====
Hooks
=====

Hooks are code that are set to execute at specific points in the processing of
a Pancake-powered form, either before a form is displayed or after it has
passed validation.  You can use hooks to email the submitted form data,
send a confirmation email, disable the form after a specific date, and much
more.  Pancake includes a handful of :doc:`built-in hooks </references/hooks>`.

Adding hooks to your form
=========================

You add a hook to your form using the ``Pancake::addHook()`` method:

.. function:: Pancake::addHook($type, $hook[, $settings])
    
    Adds a hook to the form.
    
    :param str $type: ``before`` (for before the form displays) or ``after``
        (for after the form validates).
    :param str $hook: Class name of the hook.
    :param arr $settings: Associative array of the settings wherein
        the key is the name of the setting.

Below are some examples of hooks being added to a Pancake-powered form.

.. code-block:: php
    
    <?php
    $form->addHook(
        'before',
        'AdminBefore',
        array(
            'form_key' => 'homecoming/2010/parade'
        )
    );
    
    $form->addHook(
        'after',
        'EmailForm',
        array(
            'to' => 'example@example.com',
            'from' => 'email'
        )
    );
    ?>

.. note::
    If you are adding a custom hook to your form, you should use a
    `fully-qualified name
    <http://php.net/manual/en/language.namespaces.rules.php>`_ to ensure
    that the name is correctly resolved.

Creating your own hooks
=======================

It is fairly easy to create your own hooks.  They should extend the
``\Pancake\Hook\Hook`` class, whose details are listed below.

.. class:: Hook
    
    Base hook class.
    
    :var arr $_settings: Hook settings.
    :var arr $_validSettings: Valid hook settings.
    :var arr $_requiredSettings: Required settings.
    
    .. method:: _init()
    
        Hook-specific constructor.
    
    .. method:: run($fields)
    
        Hook logic.
        
        :param arr $fields: Form fields.
        :returns: ``true`` if all is successful or an error message otherwise.

The ``$fields`` argument that is passed to the hook at runtime is an array of
the form fields.  Each entry has a number of useful public properties, some of
which are listed below:

**name**
  The name of the field.
**value**
  The value of the field.  For example, a :ref:`checkbox <field-checkbox>`'s
  value is ``true`` or ``false``.
**formattedValue**
  The formatted value of the field.  For example, a
  :ref:`checkbox <field-checkbox>`'s formatted value
  is ``Yes`` or ``No``.
**label**
  The label of the form field.

Below is an example of a custom hook that uses the `Zend Framework
<http://framework.zend.com/>`_ to add a new row to a database which is
populated by data from the submitted form:

.. code-block:: php

    <?php
    /**
     * Adds an application row to the database
     * 
     * @package jobs
     */
    class JobsApplicationHook extends \Pancake\Hook\Hook
    {
        /**
         * @param  array $fields
         * @return boolean
         */
        public function run($fields)
        {
            $applications = new \Jobs\Model\Applications;
            
            $application = array(
                'posting_id' => $fields['posting_id']->formattedValue,
                'name' => $fields['name']->formattedValue,
                'email' => $fields['email']->formattedValue,
                'status' => 'N'
            );
            
            return $applications->insert($application) !== false;
        }
    }
    ?>