NAME

Form::Sensible::Form - Form::Sensible's Form class

SYNOPSIS

    use Form::Sensible::Form;
    
    my $form = Form::Sensible::Form->new( name => 'login_form' );

    $form->add_field({ ... });
    
    # later
    
    $form->set_values( $cgi->Vars );
    
    my $validation_result = $form->validate();

    if ( !$validation_result->is_valid() ) {
        # re-render form with errors.
    }

DESCRIPTION

Form::Sensible::Form is the main class in the Form::Sensible module. It represents a complete set of fields to be presented to the user in more or less a single transaction. Unlike an HTML form which has certain presentation and behaviors associated with it, a Form::Sensible::Form is simply a container of fields. Forms exist primarily as a handle to allow easy operation upon a group of fields simultaneously. Note that while Forms may only contain Fields, it is possible to include forms into other forms by using subforms (Form::Sensible::Field::SubForm)

Note also that Renderer and Validator objects are built to operate on potentially multiple Forms during their lifecycle. The render() and validate() are primarily convenience routines.

ATTRIBUTES

name

The name of this form. Used mainly to identify a particular form within renderers.

render_hints

A hashref containing global form-level rendering hints. Render hints are used to give renderers clues as to how the form should be rendered.

validation

Hashref containing arguments to be used during complete form validation (which runs after each individual field's validation has run.) Currently only supports a single key, code which provides a coderef to run to validate the form. When run, the form, and a prepared Form::Sensible::Validator::Result object are passed to the subroutine call.

validator_args

Hashref containing arguments to the validator class to be used when a validator object is created 'on demand'.

renderer

The renderer object associated with this form, if any. May be set to enable the $form->render() shortcut.

The following attributes are set during normal operating of the Form object, and do not need to be set manually. They may be overridden, but if you don't know exactly what you are doing, you are likely to run into very hard to debug problems.

field_order

An array reference containing the fieldnames for the fields in the form in the order that they should be presented. While this may be set manually, it's generally preferred to use the add_field and reorder_field to set field order.

validator

The validator object associated with this form, if any. May be set manually to override the default $form->validate() behavior.

validator_result

Contains a Form::Sensible::Validator::Result object if this form has had it's validate() method called.

METHODS

new( %options )

Creates a new Form object with the provided options. All the attributes above may be passed.

add_field( $field, $fieldname, $position )

Adds the provided field to the form with the given fieldname and position. If $fieldname is not provided the field will be asked for it's name via it's $field->name method call. If $position is not provided the field will be appended to the form. The $field argument may be an object of a subclass of Form::Sensible::Field OR a simple hashref which will be passed to Form::Sensible::Fields create_from_flattened() method in order to create a field.

remove_field( $fieldname )

Removes the field identified by $fieldname from the form. Using this will update the order of all fields that follow this one as appropriate. Returns the field object that was removed.

reorder_field( $fieldname, $new_position )

Moves the field identified by $fieldname to $new_position in the form. All other fields positions are adjusted accordingly.

field( $fieldname )

Returns the field object identified by $fieldname.

fields()

Returns a hash containing all the fields in the current form.

fieldnames()

Returns an array of all the fieldnames in the current form. Order is not guaranteed, if you need the field names in presentation-order, use field_order() instead.

set_values( $values )

Uses the hashref $values to set the value for each field in the form. This is a shortcut routine only and is functionally equivalent to calling $field->value( $values->{$fieldname} ) for each value in the form.

get_all_values()

Retrieves the current values for each field in the form and returns them in a hashref.

clear_state()

Clears all state related data from the form. Returns form to the state it was in prior to having any values set or validation run.

validate()

Validates the form based on the validation rules provided for each field during form creation. Delegates it's work to the validator object set for this form. If no validator object is set, a new Form::Sensible::Validator will be created.

render( @options )

Renders the current form using the renderer object set for this form. Since different renderers require different options, the @options are specific to the renderer and are passed as-is to the renderer's render() method. Returns a rendered form handle object. Note that rendered form handle objects are specific in type and behavior to the renderer being used, please refer to the renderer's documentation for the proper way to use the rendered form object.

flatten( $template_only )

Returns a hashref containing the state of the form and all it's fields. This can be used to re-create the entire form at a later time via Form::Sensibles create_form() method call. If $template_only is true, then only the structure of the form is saved and no values or other state will be included in the returned hashref.

AUTHOR

Jay Kuri - <jayk@cpan.org>

SPONSORED BY

Ionzero LLC. http://ionzero.com/

SEE ALSO

Form::Sensible

LICENSE

Copyright 2009 by Jay Kuri <jayk@cpan.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.