CREATING AND RENDERING A FORM

    use Form::Sensible;
    
    my $form = Form::Sensible->create_form(
        {
            name => 'login_form',
            fields => [
                         {
                            field_class => 'Text',
                            name => 'username',
                            validation => {
                                    regex => '^[0-9a-z]*',
                                    required => 1,
                                }
                         },
                         {
                             field_class => 'Text',
                             name => 'password',
                             validation => {
                                    required => 1,
                                },
                             render_hints => {
                                    'HTML' => {
                                                render_as => 'password'
                                              }
                                    },
                         },
                         {
                             field_class => 'Trigger',
                             name => 'submit'
                         }
                      ],
        } );

The above code snippet creates the all-too-familiar login form we are used to. Each field has a " field_class ", which corresponds with a "Form::Sensible::Field" classname, and a "name" which is used to get a hold of this particular field. The "name" element for any given field should be unique within the form.

Something to notice here is that all validation information required for validating this form is present in this definition. Another thing to notice is that we use a standard "Text" field to store our password data. Remember that "Form::Sensible" field definitions are centered around the data you want to collect, not how they are presented. In this case, we simply ask the HTML renderer to render it as a "password" by providing "render_hints". We'll come back to "render_hints" later.

Now that we have a form, though, what do we do with it? Well, in most cases we want to render it. That is astoundingly simple. First we ask for the renderer we want, then we use the renderer to render the form:

    my $renderer = Form::Sensible->get_renderer('HTML');
    my $renderedform = $renderer->render($form);

At this point, we have a $renderedform. This is not, however, a string. The output of a Form::Sensible renderer is a 'rendered form handle.' What that means is specific to the type of Renderer being used. What they have in common, though, is that they are an object that can be used to actually initiate user interaction. They are also connected directly to the $form object which was used to create them. This means that changes to the $form object will be reflected in the User Interface and that values will be set in the $form in response to user action on the renderedform.

For HTML, this connection is limited by the transactional nature of HTTP, but it is still there and any changes you make to $form prior to actually presenting the rendered form will be reflected in the HTML generated.

Ok... so we have a $renderedform. Now what do we do? We display it, obviously. For an HTML form, that looks like this:

    print $renderedform->complete('/login', 'post');

This would print out the form rendered as HTML. The first argument to "complete()" is the action to submit this HTML form to. This is passed directly through to the generated "<form>" element's " action " attribute. The second argument is the method, either 'get' or 'post', and is likewise passed directly through to the " method " attribute on the form element.

In terms of rendering, we are done. The HTML representation of the form will be generated and printed out.

SETTING VALUES AND VALIDATION

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

The form is smart enough to recognize the fields it cares about and to load the values as appropriate. Note, however, that validation is not done at this point. It is entirely possible to put bad data into the values for the various fields. To make sure that what we got is valid, we call "$form->validate()":

    my $result = $form->validate();

Calling "$form->validate()" runs through all field and form validation according to the form definition and produces a Form::Sensible::Validator::Result object. The result object can then be used to indicate what exactly went wrong, if anything:

    if ($result->is_valid()) {
        # do valid-form stuff here.
        authenticate_user($form->field('username')->value, $form->field('password')->value);
    } else {
        my $renderer = Form::Sensible->get_renderer('HTML');
        my $renderedform = $renderer->render($form);
        $renderedform->add_errors_from_validator_result($result);
        print $renderedform->complete('/login','post');
    }

If "$result->is_valid()" is true, we can proceed to doing what we need to do with the form data. An interesting thing to note here is that if the form is invalid, we simply redisplay the form.

You've now gone through the entire lifecycle of a "Form::Sensible" form. We have used the HTML renderer because it is most familiar (and it is the only publicly released renderer at this point.) That said, however, for the most part only the "print" line and "set_values" line are likely to change to present using a different renderer.

VALIDATION

Form and Field validation in Form::Sensible is fairly straightforward. Each field has a "validation" hashref which defines three elements for field validation: "required", "regex", and "code". The "required" element is simply a true/false flag indicating whether it is an error if the field is empty. The "regex" element is exactly what it sounds like. The value for the field is checked against the regex provided; if it does not match, the field is marked invalid. The last element, "code", is the most interesting. Its value is a coderef for a subroutine that checks the field's value. The subroutine provided is called with two arguments, first the field's value, then the field object itself. The subroutine is expected to return either a zero (0) value - indicating the field is OK, or a message indicating why the field is invalid. This is somewhat non-intuitive as you return 0, or a false value, to indicate the field is ok if you are not familiar with exit codes on UNIX-like platforms. If that is the case, it may help to think about the "code" coderef as a question, 'Is this value invalid?' An example of a "code" validator is:

    validation => {
                ## remember this is answering the question 'is_this_invalid()'
        code => sub {
                        my ($value, $field) = @_;
                        if ($value ne $field->name) {
                            return "_FIELDNAME_ is a bizarre field that can only contain its own name.  Field is invalid.";
                        } else {
                            ## I contain my own name, that means this validation should pass.  return 0.
                            return 0;
                        }
                    }
    }

Note in the example above the string '_FIELDNAME_' is used in place of the actual field name. This works this way to allow for easy localization of strings. This will be translated to the field's name later.

Validation is not an either-or: you can have both a regex and a coderef for validation and if you do, both must be successful for the value to be considered valid. When you provide both, the regex is tested first and if the value passes the regex check, then the coderef is run. Note that if the regex failed, the coderef subroutine will not be called.

Note that some field types have their own validation. For example, Select fields will not accept any value that is not part of their option list. Numbers, likewise, perform their own validation to check against their upper and lower bounds and other related items. If a field type has a builtin validator routine, it will be run after the regex and coderef are run. Unlike the coderef, however, the field's builtin validation routine is run regardless of the results of regex or coderef validators.

Another thing to note about Field validation is that if the field is empty no validation will be run and the form itself will be marked 'invalid.' The field itself will be marked as 'invalid' if it is not required and 'missing' if it is required. See "Error Messaging".

Complete Form validation

If field validation is completed successfully, the final step in form validation is run. That step is 'complete form validation.' You can provide a "validation" hashref on the form itself which will be run after all other fields have been validated (if and only if all the fields individually are valid.) The subroutine for a form is slightly different than the coderef for a field. The arguments are the form object and the validator result object that was created for this validation. Rather than returning any particular value, a form validation coderef should manipulate the validator result object directly. For example:

    # ... rest of form definition
    validation => {
        code => sub {
                        my ($form, $result) = @_;
                        if ($form->field('password')->value() ne $form->field('password2')->value()) {
                            ## add an error on the 'password' field.
                            $result->add_error('password', "Your passwords do not match, please try again.");
                        }
                    }
    }

Error Messaging

Finally we need to cover error messaging. With code-based validation of either Fields or the entire form, you provide the error message to use. For other types of validation (including regex and field-specific validation) you may want to provide custom error messages. If you want to provide a custom error message for a field you can provide two additional elements to the "validation" hashref: "invalid_message" and "missing_message". Both of these are strings that will be used in place of the generic 'FieldX is invalid' type messaging. As you might suspect, "invalid_message" is used when a field is found to be invalid. The "missing_message" is used if the field is required but is not set. An example of custom messaging:

    # ... rest of field definition
    validation => {
                    regex => '^\d\d\d-\d\d\d-\d\d\d\d$',
                    invalid_message => "Phone must be formatted as ###-###-####",
                    missing_message => "Please provide a Phone number."
    }

RENDERING

Render hints are a way to help the renderer decide how to present the field or form you are working with. Render hints can be placed into the form definition itself or can be inserted at various points along the rendering path. Generally speaking, the hints that are closest to final rendering take precedence over those at a higher distance.

That is to say that if you have "render_hints" provided for the field in the "render_field()" call, they will override any hints set in the "complete()" call which in turn would override any hints set in the field's original definition. Note that the all of the "render_hints" are merged before processing occurs with those closer to the actual rendering taking precedence on conflict.

Render hints are most often applied to fields, though they can be applied to Forms as well. How render hints are applied are specific to the renderer being used. An example of render hints might be:

    {
        field_class => 'Number',
        lower_bound => 1910,
        upper_bound => 2010,
        step => 1,
        render_hints => {
            HTML => {
                field_type => 'Select',
                render_as => 'checkboxes'
            }
        }
    }
The C<render_hints> here tells the HTML render that this should be rendered
the way a Select field is rendered instead of the way a Number is normally
rendered (a text field). It also tells the renderer that when it is rendering
the Select C<field_type> it should render the select as a series of checkboxes
instead of a dropdown (the default for Select type).

The 'HTML' in the above example addresses that section to the HTML renderer, other renderers would not be affected by the render hints provided. This allows you to provide "render_hints" for the field that are specific for.

... More to come.

# JK - pick up here.