/ 
Form-Sensible-0.20023
River stage one • 2 direct dependents • 2 total dependents
/ Form::Sensible::Form

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.

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.

DELEGATES

Delegates are objects that help determine certain behaviors. These delegates allow control over form behavior without subclassing. See Form::Sensible::DelegateConnection for more information.

should_process_field_delegate->($self, $fieldname)

Returns true/false on whether the field should be included in general form processing. Default behavior is to always return true, hence indicating all fields present should be processed. This is used when <$form-get_fields()>> is called. It essentially gives you a mechanism for disabling rendering and validation of particular fields on demand.

validation_delegate->($self)

Runs validation on the form. Returns a Form::Sensible::Validator::Result object representing the results of the validation process. If not provided and <$form-validate()>> is run, a Form::Sensible::Validator object will be created.

METHODS

new( %options )

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

delegate_all_field_values( $delegate_connection )

Loops over all fields in the form and delegates their values to the provided $delegate_connection

delegate_all_field_values_to_hashref( $hashref )

Loops over all fields in the form and delegates their values to the given hashref using the field's name as the key. Note that this will capture the hashref provided within a closure. If your form / field objects are likely to outlive your hashref, such as in the case of a persistent form object used within a Catalyst Request it is recommended that you instead delegate the values to an intermediate object that can obtain the values for the current request

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.

get_fields()

Returns an array containing all the fields in the current form in field order. Affected by should_process_field_delegate. If should_process_field_delegate returns false for a given field, it will be excluded from the results of get_fields(). NOTE: When performing any action on all fields in a form, you should use this method to ensure that any fields that should not be processed are excluded.

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 via the validation_delegate set for this form. If no validation_delegate object is set, a new Form::Sensible::Validator will be created and attached as appropriate.

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.

DEPRECATED

These method calls have been deprecated and will be removed. They exist here only to help make sense of existing code... and to warn you they are being removed.

fields() (DEPRECATED 2010-06-13 - To be removed 2010-08-30)

Returns an hashref containing all the fields in the current form

validator (DEPRECATED 2010-06-13 - To be removed 2010-08-30)

The validator object associated with this form, if any.

validator_result (DEPRECATED 2010-06-13 - To be removed 2010-08-30)

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

validator_args (DEPRECATED 2010-06-13 - To be removed 2010-08-30)

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

renderer (DEPRECATED 2010-06-13 - To be removed 2010-08-30)

The renderer object associated with this form, if any.

render( @options ) (DEPRECATED 2010-06-13 - To be removed 2010-08-30)

Renders the current form using the renderer object set for this form.

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.