view release on metacpan or  search on metacpan

lib/HTML/FormFu/Manual/Cookbook.pod  view on Meta::CPAN

If you want to display an error message due to an error in your own code,
such as a database check; something which isn't implemented as a
L<Constraint|HTML::FormFu::Constraint> or
L<Validator|HTML::FormFu::Validator>; you can use a
L<Callback Constraint|HTML::FormFu::Constraint::Callback>.

If you don't provide your own callback routine, the default callback will
always pass, regardless of user input.

You can take advantage of this by setting
L<force_errors|HTML::FormFu/force_errors>, to display its error message
when needed.

Example config:

    ---
    elements:
      - type: Text
      - name: email
      - constraints:
        type: Callback
        message: 'Email address already in use'

Example usage:

    if ( $@ =~ m/duplicate entry for key 'email'/i ) {

        $form->get_field('email')
             ->get_constraint({ type => 'Callback' })
             ->force_errors(1);

        $form->process;
        # then redisplay the form as normal
    }

=head2 Highlight required fields (or fields with certain types of constraint)

This can be achieved using the form's C<auto_constraint_class> method:

    $form->auto_constraint_class( 'constraint_%t' );

The container divs around any form field with a constraint will then have extra
CSS classes added, which indicate the type of constraint and allow you to apply
appropriate styling with CSS:

    /* change background of labels for fields with a Required constraint */
    fieldset .constraint_required label {
        background: #f00;
    }

This technique can also be used to add content before or after the fields in
question (note this will not work in older browsers with more limited CSS
support such as IE6):

    /* add an asterisk at the end of the label for required fields */
    fieldset .constraint_required label:after {
        content: '*'
    }

=head2 Add a popup hint to a field

Most display a tooltip when a user hovers their mouse pointer over an HTML
element with a "title" tag.
Aural browsers may try to turn the content into speech.
You can take advantage of this behaviour to provide a hint to the user about
how to complete a form field.

    elements:
      - type: URL
        name: url
        label: Website
        title: 'Must start with http:// or https://'

The above will provide a hint when the "url" field receives focus.
Or you could provide the hint for the container tag around both field and label:

    elements:
      - type: URL
        name: url
        label: Website
        container_attributes:
            title: 'Must start with http:// or https://'

=head2 Display filtered values

If you have a Filter on a field, such as L<HTML::FormFu::Filter::Whitespace>
to strip leading / trailing whitespace, then if you redisplay the form the
field is normally populated with the value the user originally entered.

If you would like the field to contain the filtered value, use
L<HTML::FormFu/render_processed_value>.

=head2 Multiple forms using Catalyst::Controller::HTML::FormFu

Sometimes you need to display multiple forms on a single page. If you
try to use FormConfig on several actions in a chain, or similar, they
all use C<< $c->stash->{form} >> to store the form, hence you only get the last
form.

One way to work around such problems is to do a little of the work yourself:

In this example we have a login_form that we want on every page

    # root/forms/login.yml:
    ---
        indicator: username
        elements:
            -
                type: Text
                name: username
                constraints:
                    - Required
    ...

We also have an edit-form

    # root/forms/foo/edit.yml
    ---
        indicator: foo
        elements: