.. _hooks-label:

Hooks
=====

Hooks are functions that are used to add more functionality to the handler.
There can be zero more of each type of hook except for `get_schema`.

update_defaults
---------------

This hook adds defaults to be used during the prompt stage of form handling. 
A hook function might look like this:

.. code-block:: python

    def set_user_email(handler_instance, defaults, state):
        defaults['email'] = state.user.email
        return defaults

    form_handler = FormHandler(schema=schema,
            update_defaults_hooks=[set_user_email])

get_schema
----------

This hooks lets the developer dynamically determine which schema to use for
form validation.  It should be obvious but just a reminder these params have
received no validation and must be considered unsafe.  Also there should only
be zero or one of this type of hook.  If this hook is not set the schema
attribute of the handler is used for validation. An example of choosing a
schema for a product's information based on the product's type might look like
this:

.. code-block:: python

    def get_schema(handler_instance, unsafe_params, state):
        if unsafe_params.get('product_type', None) == 'advanced':
            return advanced_product_schema
        else:
            return simple_product_schema

    form_handler = FormHandler(get_schema_hook=get_schema)
    

update_state
------------

This hooks is called during both prompt and process and can be used to
add attributes to state based on access to global variables. Here is a
completely fabricated example that sets today's date on the state object.

.. code-block:: python

    def set_today(handler_instance, defaults, state):
        state.today = date.today()

    form_handler = FormHandler(update_state_hooks=[set_today])


on_process_error
----------------

This hook is called when validation fails.  It is useful to add or remove
things before rendering the form again.  This example removes the password:

.. code-block:: python

    def remove_password(handler_instance, defaults, errors, state):
        if defaults.has_key('password'):
            del defaults['password']
        return defaults

    form_handler = FormHandler(on_process_error_hooks=[remove_password])

defaults_filter
---------------

This hook pre-processes the defaults passed to process.  This is useful to
remove/add/alter the defaults before validation. Here is an example that
removed keys ending in '--system'.

.. code-block:: python

    def filter_system_params(handler_instance, unsafe_params, state):
        for k in unsafe_params.keys():
            if k.endswith('--system'):
                del unsafe_params[k]
        return unsafe_params

    form_handler = FormHandler(defaults_filter_hooks=[filter_system_params])


customize_fill_kwargs
---------------------

This hook is useful to inject kwargs used for filling the form. Here is an
example that adds an error formatter and tells htmlfill to use it by default.


.. code-block:: python

    from formencode.htmlfill import html_quote, default_formatter_dict

    error_class = 'std_error'

    error_formatters = default_formatter_dict.copy()

    def std_formatter(error):
        return '<span class="%s">%s</span>' % \
                (error_class, html_quote(error))
    
    error_formatters['std'] = std_formatter
    
    def add_std_error_formatter(handler_instance, defaults, errors, state,
            fill_kwargs):
        fill_kwargs.update({
            'error_class': error_class,
            'error_formatters': error_formatters,
            'auto_error_formatter': error_formatters['std'],
        })
        return fill_kwargs

    form_handler = FormHandler(
            customize_fill_kwargs_hooks=[add_std_error_formatter])