NAME

Fields

I have a hash that contains the field values, what's the best way to get those into a Form::Sensible form?

There are two ways to do this. The preferred way is usually to delegate your form's field values to your hash. You often want to do this to link a form's fields to a single source of data, for example, Catalyst's "$c->req->params" hashref. This can be done easily using the Form::Sensible::Form's delegate_all_field_values_to_hashref routine:

 $form->delegate_all_field_values_to_hashref($c->req->params);
    

After that, all fields will get and set their values via the "$c->req->params" hashref.

NOTE that this is actually a very bad idea if your forms are persistent from one request to the next, as the "$c->req->params" from the initial request will be captured within a closure. If you are using persistent forms, you must re-set the delegate during each request or use an intermediate object instead that can obtain the current request's parameters.

If you have not delegated your field's values to something else (as indicated above), the form itself will store the values. In this case, you must push the values into the form object instead. You can accomplish this by calling "$form->set_values($your_hashref);"

How do I disable a field?

Simply set the field's '"editable"' attribute to false. "Form::Sensible" will ensure that the field is not editable by the end user. Note that when a field is disabled in HTML, the browser does NOT send the value when the form is submitted. "Form::Sensible"'s HTML renderer takes this into account and if a value exists on a field that is marked as not editable, a hidden field will be added to transport the value back to the form processor.

Can I set the options for my Select field directly from a DBIx::Class resultset?

Yes. This is actually quite easy. You define an "options_delegate" on the Select field and use a subroutine similar to the following:

 ## defined as a named subroutine so that it can be reused as often as needed.
 sub get_options_from_rs {
     my $caller = shift;
     my $option_details = shift;

     $option_details->{rs}->reset;
     return [
               map {
                    name => $_->get_column($option_details->{name_column}),
                    value => $_->get_column($option_details->{value_column})
                  } $option_details->{rs}->all()
            ];
 }
    

Then set the "options_delegate" to use that function and pass the appropriate information:

 $field->options_delegate( FSConnector( \&get_options_from_rs,
     {
        rs => $your_resultset->search({ ... }),
        name_column => 'name',
        value_column => 'id',
     }
     ));
    

The FSConnector will pass your "option_details" hash to the "get_options_from_rs" function, and your options will be pulled from the database when they are needed (whether for validation or for display).

Validation

How do I create validation that involves multiple fields (like password and confirmation fields)?

Individual field based validation is handled via the individual field's "validation" hash. If you want to check multiple fields together you need to do whole-form level validation. This can be accomplished easily via the form's "validation" hash as follows:

    $form->validation({
                        code => sub {
                                my ($form, $result) = @_;
                                
                                if ($form->field('password')->value() ne $form->field('password2')->value()) {
                                    $result->add_error('password2', 'Passwords do not match');
                                }
                        }
    });
    

HTML Rendering

Delegates

Miscelleneous Questions

How do I localize field names and error messages?

Localization of forms can be accomplished through the use of delegates. Both the Form::Sensible::Validator class and Form::Sensible::Renderer::HTML::RenderedForm support localizing through delegates.

By providing a "DelegateConnection|Form::Sensible::DelegateConnection" to Form::Sensible::Validator's message_delegate you can translate the error or status messages as necessary.

You can translate field names in the form in the same way by providing a "DelegateConnection|Form::Sensible::DelegateConnection" to Form::Sensible::Renderer::HTML::RenderedForm's display_name_delegate

I'm using Catalyst and I would like my form objects to be persistent from one request to the next, how do I do that?

BEWARE: Here lie Monsters and really freaky problems

Generally speaking, it is a bad idea to persist forms from one request to the next within Catalyst. The main reason is that you can not reliably delegate in many cases because many of Catalyst's objects (such as Models and Controllers) can be created and destroyed within the request lifecycle in certain scenarios. This can be very difficult to predict and is prone to accidental breakage and bleed over.

If you feel you must try to do this, you have two options:

Where can I go for help using "Form::Sensible"

You can join the google discussion group:

<http://groups.google.com/group/formsensible>

OR look at the wiki:

<http://wiki.catalyzed.org/cpan-modules/form-sensible>

OR drop by the irc channel:

irc.perl.org#form-sensible Join #form-sensible via your web browser <http://mibbit.com/#form-sensible@irc.perl.org>

AUTHORS

SPONSORED BY

COPYRIGHT & LICENSE