view release on metacpan or  search on metacpan

lib/HTML/FormFu.pm  view on Meta::CPAN

    sub edit : Chained('user') Args(0) FormConfig {
        my ( $self, $c ) = @_;

        my $form = $c->stash->{form};
        my $user = $c->stash->{user};

        if ( $form->submitted_and_valid ) {

            $form->model->update( $user );

            $c->res->redirect( $c->uri_for( "/user/$id" ) );
            return;
        }

        $form->model->default_values( $user )
            if ! $form->submitted;

    }

Note: Because L</process> is automatically called for you by the Catalyst
controller; if you make any modifications to the form within your action
method, such as adding or changing elements, adding constraints, etc;
you must call L</process> again yourself before using L</submitted_and_valid>,
any of the methods listed under L</"SUBMITTED FORM VALUES AND ERRORS"> or
L</"MODIFYING A SUBMITTED FORM">, or rendering the form.

Here's an example of a config file to create a basic login form (all examples
here are L<YAML>, but you can use any format supported by L<Config::Any>),
you can also create forms directly in your perl code, rather than using an
external config file.

    ---
    action: /login
    indicator: submit
    auto_fieldset: 1

    elements:
      - type: Text
        name: user
        constraints:
          - Required

      - type: Password
        name: pass
        constraints:
          - Required

      - type: Submit
        name: submit

    constraints:
      - SingleValue

=head1 DESCRIPTION

L<HTML::FormFu> is a HTML form framework which aims to be as easy as
possible to use for basic web forms, but with the power and flexibility to
do anything else you might want to do (as long as it involves forms).

You can configure almost any part of formfu's behaviour and output. By
default formfu renders "XHTML 1.0 Strict" compliant markup, with as little
extra markup as possible, but with sufficient CSS class names to allow for a
wide-range of output styles to be generated by changing only the CSS.

All methods listed below (except L</new>) can either be called as a normal
method on your C<$form> object, or as an option in your config file. Examples
will mainly be shown in L<YAML> config syntax.

This documentation follows the convention that method arguments surrounded
by square brackets C<[]> are I<optional>, and all other arguments are
required.

=head1 BUILDING A FORM

=head2 new

Arguments: [\%options]

Return Value: $form

Create a new L<HTML::FormFu|HTML::FormFu> object.

Any method which can be called on the L<HTML::FormFu|HTML::FormFu> object may
instead be passed as an argument to L</new>.

    my $form = HTML::FormFu->new({
        action        => '/search',
        method        => 'GET',
        auto_fieldset => 1,
    });

=head2 load_config_file

Arguments: $filename

Arguments: \@filenames

Return Value: $form

Accepts a filename or list of file names, whose filetypes should be of any
format recognized by L<Config::Any>.

The content of each config file is passed to L</populate>, and so are added
to the form.

L</load_config_file> may be called in a config file itself, so as to allow
common settings to be kept in a single config file which may be loaded
by any form.

    ---
    load_config_file:
      - file1
      - file2

YAML multiple documents within a single file. The document start marker is
a line containing 3 dashes. Multiple documents will be applied in order,
just as if multiple filenames had been given.

In the following example, multiple documents are taken advantage of to
load another config file after the elements are added. (If this were
a single document, the C<load_config_file> would be called before

lib/HTML/FormFu.pm  view on Meta::CPAN

Return Value: $model

=head2 model_config

Arguments: \%config

=head1 MODIFYING A SUBMITTED FORM

=head2 add_valid

Arguments: $name, $value

Return Value: $value

The provided value replaces any current value for the named field. This
value will be returned in subsequent calls to L</params> and L</param> and
the named field will be included in calculations for L</valid>.

=head2 clear_errors

Deletes all errors from a submitted form.

=head1 RENDERING A FORM

=head2 render

Return Value: $string

You must call L</process> once after building the form, and before calling
L</render>.

=head2 start

Return Value: $string

Returns the form start tag, and any output of L</form_error_message> and
L</javascript>.

=head2 end

Return Value: $string

Returns the form end tag.

=head2 hidden_fields

Return Value: $string

Returns all hidden form fields.

=head1 PLUGIN SYSTEM

C<HTML::FormFu> provides a plugin-system that allows plugins to be easily
added to a form or element, to change the default behaviour or output.

See L<HTML::FormFu::Plugin> for details.

=head1 ADVANCED CUSTOMISATION

By default, formfu renders "XHTML 1.0 Strict" compliant markup, with as
little extra markup as possible. Many hooks are provided to add
programatically-generated CSS class names, to allow for a wide-range of
output styles to be generated by changing only the CSS.

Basic customisation of the markup is possible via the
L<layout|HTML::FormFu::Role::Element::Field/layout> and
L<multi_layout|HTML::FormFu::Role::Element::Field/multi_layout> methods.
This allows you to reorder the position of various parts of each field -
such as the label, comment, error messages and the input tag - as well
as inserting any other arbitrary tags you may wish.

If this is not sufficient, you can make completely personalise the markup
by telling HTML::FormFu to use an external rendering engine, such as
L<Template Toolkit|Template> or L<Template::Alloy>.
See L</render_method> and L</tt_module> for details.

Even if you set HTML::FormFu to use L<Template::Toolkit|Template> to render,
the forms, HTML::FormFu can still be used in conjunction with whichever other
templating system you prefer to use for your own page layouts, whether it's
L<HTML::Template>: C<< <TMPL_VAR form> >>,
L<Petal>: C<< <form tal:replace="form"></form> >>
or L<Template::Magic>: C<< <!-- {form} --> >>.

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

=head2 render_method

Default Value: C<string>

Can be set to C<tt> to generate the form with external template files.

To customise the markup, you'll need a copy of the template files, local to
your application. See
L<HTML::FormFu::Manual::Cookbook/"Installing the TT templates"> for further
details.

You can customise the markup for a single element by setting that element's
L</render_method> to C<tt>, while the rest of the form uses the default
C<string> render-method. Note though, that if you try setting the form or a
Block's L</render_method> to C<tt>, and then set a child element's
L</render_method> to C<string>, that setting will be ignored, and the child
elements will still use the C<tt> render-method.

    ---
    elements:
      - name: foo
        render_method: tt
        filename: custom_field

      - name: bar

    # in this example, 'foo' will use a custom template,
    # while bar will use the default 'string' rendering method

This method is a special 'inherited accessor', which means it can be set on
the form, a block element or a single element. When the value is read, if
no value is defined it automatically traverses the element's hierarchy of
parents, through any block elements and up to the form, searching for a