Default search paths for config files

If you're using the "FormConfig" action attribute from Catalyst::Controller::HTML::FormFu, forms should be saved in "root/forms". See "SYNOPSIS" in Catalyst::Controller::HTML::FormFu and "config_file_path" in Catalyst::Controller::HTML::FormFu for further details.

YAML

A form can be populated by a config file by calling "load_config_file" in HTML::FormFu with the filename as an argument. The config file is converted to a perl data-structure, and then passed to "populate" in HTML::FormFu.

The config file must contain a hash-ref, with the keys corresponding to form method-names, and the values being the method arguments. For example, the following are equivalent:

    ---
    auto_fieldset: 1
    elements:
      - name: foo
      - name: bar

    # the above YAML is equivalent to the following perl code

    $form->auto_fieldset(1);

    $form->elements([
        { name => 'foo' },
        { name => 'bar' },
    ]);

When writing your config file, remember that perl hashes are unordered and cannot have multiple keys with the same name.

See "load_config_file" in HTML::FormFu and "populate" in HTML::FormFu for more details.

See <http://www.yaml.org/spec/> for the YAML specification.

Quick single-file prototypes

    #!/usr/bin/perl
        use warnings;
    use HTML::FormFu;
    use YAML::XS qw( LoadFile );

    my $form = HTML::FormFu->new;
    my $data = LoadFile(\*DATA);

    $form->populate($data);

    print $form;

    __DATA__
    ---
    auto_fieldset: 1
    elements:
      - type: Text
        name: foo

Unsupported HTML tags

    ---
    elements:
      - type: Block
        tag: span
        content_xml: "<b>Hi!</b>"

You can use "content" in HTML::FormFu::Element::Block, "content_xml" in HTML::FormFu::Element::Block or "content_loc" in HTML::FormFu::Element::Block to add any content you wish, or use "element" in HTML::FormFu::Element::Block to add elements.

Insert a new field before existing form fields

    my $fieldset = $form->get_element({ type => 'Fieldset' });

    $fieldset->insert_before(
        $form->element(\%specs),
        $form->get_field($name)
    );

Another way to approach the problem is to use multiple config files, and decide which to load at runtime:

    # user_edit.yml
    ---
    elements:
      - type: Text
        name: email

    # user_username.yml
    ---
    elements:
      - type: Text
        name: username

     # user_register.yml
     ---
     load_config_file:
      - user_username.yml
      - user_edit.yml

    # create a user edit form, with only the email field

    $form->load_config_file( 'user_edit.yml' );

    # create a user registration form with username and email fields

    $form->load_config_file( 'user_register.yml' );

Form and Field attributes

    ---
    attributes_xml:
      onsubmit: "js_function()"
    elements:
      - type: Text
        name: foo
        attributes_xml:
          onchange: "js_function()"

Check valid dates

Check valid URI / URLs

Implement a custom constraint / validator

It should implement a "validate_value" method, which returns true is the value is valid, or false otherwise.

    package My::Custom::Validator;
    use Moose;
    extends 'HTML::FormFu::Validator';

    sub validate_value {
      my ( $self, $value, $params ) = @_;

      return 1 if value_is_valid( $value );

      return;
    }

    1;

Then add your custom validator to the form:

    ---
    elements:
      - type: Text
        name: foo
        validators:
          - '+My::Custom::Validator'

Constrain one form field based on the value of another

This is achieved using the "when" attribute of a constraint:

    constraints:
      - type: Length
        min: 8
        when:
          field: bar
          values: [ 1, 3, 5 ]

In the above example, the Length constraint is only processed when the form field named "bar" has a value of either 1, 3 or 5.

You can also test for a negative condition using the "not" attribute:

    constraints:
      - type: Length
        min: 8
        when:
          field: bar
          values: [ 1, 3, 5 ]
          not: 1

Now the constraint will be processed only if the value of field "bar" is NOT 1, 3 or 5.

Note: if you rely on the value of a checkbox for a when-restricted contraint, you might want to consider setting "default_empty_value" for that checkbox. Take a look at HTML::FormFu::Role::Element::Field to learn more.

Please read HTML::FormFu::Constraint for further information.

Constrain one form field based on the return value of a callback

For instance, the following (code) example shows a constraint being applied only if the value of another field contains a pattern

    my $apply_if_pattern = sub {
        my $params = shift;
        return 1 if $params->{other_field} =~ m/\A ice_cream \z/xms;
        return 0;
    };

    $field->{constraints} = {
        type    => 'Required',
        when    => {
            callback    => $apply_if_pattern,
        }
    }

Please read HTML::FormFu::Constraint for further information.

Indented HTML

    ---
    output_processors:
      - Indent

Add a blank div (e.g. for AJAX purposes)

    ---
    elements:
      - type: Text
        name: user

      - type: Block
        id: foo

      - type: Text
        name: email

Custom error messages

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 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
    }

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

    $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: '*'
    }

Add a popup hint to a 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://'

Display filtered values

If you would like the field to contain the filtered value, use "render_processed_value" in HTML::FormFu.

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

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:
        -
            type: Text
            name: foo
            constraints:
                - Required
    ...

In this example, we want the login form to appear on every page, so we load this in the top-most auto action:

    package MyApp::Controller::Root;

    BEGIN { extends 'Catalyst::Controller::HTML::FormFu'; }

    sub auto : Private {
        my ($self, $c) = @_;

        # We want to utilize a lot of the magic that the controller
        # gives us, so therefore we call $self->form like this

        my $login_form = $self->form;
        $login_form->load_config_file('login.yml');

        # Notice how we put it into another stash var, not 'form'
        $c->stash->{login_form} = $login_form;
        unless ($c->user_exists) {

            $login_form->process();

            if ($login_form->submitted_and_valid) {

                # Since we set indicator, we should only end up here if we
                # have a username in the form
                $c->authenticate({
                    username => $login_form->param_value('username'),
                    password => $login_form->param_value('password'),
                });
            }

        }
    }

Any other page that wants to load another form, can now do so freely:

    package MyApp::Controller::Foo;

    sub edit : Local FormConfig {
        my ( $self, $c ) = @_;

        my $form = $c->stash->{form};
        if ($form->submitted_and_valid) {
            # Do whatever you want with it :p
        }
    }

In the view we now have two stash-variables:

In root/foo/edit.tt: [% login_form %] <h2>edit</h2> [% form %]

Installing the TT templates

As of "HTML::FormFu v1.00", TT is no longer listed a required prerequisite - so you'll need to install it manually if you with to use the template files.

If you're using the Catalyst web framework, install Catalyst::Controller::HTML::FormFu and run the following command:

    $ script/myapp_create.pl HTML::FormFu

This will create a directory, "root/formfu", containing the HTML::FormFu template files.

If you extend Catalyst::Controller::HTML::FormFu and you don't set HTML::FormFu's INCLUDE_PATH yourself, it will automatically be set to "root/formfu" if that directory exists.

If you're not using Catalyst, you can create the template files by running the following command:

      $ html_formfu_deploy.pl <target-directory>

Take note that if you choose to customise your own copy of HTML::FormFu's template files, you'll need to keep track of the "Changes" file, when updating HTML::FormFu, so that you can update your own templates if the core templates are updated.

Catalyst::Plugin::StackTrace

Template::Alloy

    tt_args:
      TEMPLATE_ALLOY: 1
      COMPILE_DIR: /tmp
      COMPILE_PERL: 1

Template::Alloy's caching is off by default. Switch it on by setting either "COMPILE_EXT" or "COMPILE_DIR". If you're running under a persistent environment such as modperl or fastcgi, you should also set "COMPILE_PERL" to compile the cached templates down to perl code.

Of cource, if you wish you can still use Template::Toolkit to process your own application templates, letting Template::Alloy process just the HTML::FormFu templates.

HTML:FormFu::Preload

    use HTML::FormFu::Preload;

Force an element to always have a certain value

"retain_default" in HTML::FormFu::Role::Element::Field, "force_default" in HTML::FormFu::Role::Element::Field