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:

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:

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.

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:

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

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.

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])