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 built-in hooks.

Adding hooks to your form

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

Pancake::addHook($type, $hook[, $settings])

Adds a hook to the form.

Parameters:

• $type (str) – before (for before the form displays) or after (for after the form validates).
• $hook (str) – Class name of the hook.
• $settings (arr) – 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.

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

Variables:

• $_settings (arr) – Hook settings.
• $_validSettings (arr) – Valid hook settings.
• $_requiredSettings (arr) – Required settings.

_init()

Hook-specific constructor.

run($fields)

Hook logic.

Parameters:$fields (arr) – 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 checkbox‘s value is true or false.

formattedValue

The formatted value of the field. For example, a 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 to add a new row to a database which is populated by data from the submitted form:

<?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;
    }
}
?>