NAME

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

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

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.

AUTHOR

SPONSORED BY

SEE ALSO

LICENSE

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