NAME

VERSION

SYNOPSIS

    package MyApp::Controller::My::Controller;

    use Moose;
    use namespace::autoclean;

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

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

        # doesn't use an Attribute to make a form
        # can get an empty form from $self->form()

        my $form = $self->form();
    }

    sub foo : Local : Form {
        my ( $self, $c ) = @_;

        # using the Form attribute is equivalent to:
        #
        # my $form = $self->form;
        #
        # $form->process;
        #
        # $c->stash->{form} = $form;
    }

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

        # using the FormConfig attribute is equivalent to:
        #
        # my $form = $self->form;
        #
        # $form->load_config_filestem('root/forms/my/controller/bar');
        #
        # $form->process;
        #
        # $c->stash->{form} = $form;
        #
        # so you only need to do the following...

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

        if ( $form->submitted_and_valid ) {
            do_something();
        }
    }

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

        # using the FormConfig attribute with an argument is equivalent to:
        #
        # my $form = $self->form;
        #
        # $form->load_config_filestem('root/forms/my_config');
        #
        # $form->process;
        #
        # $c->stash->{form} = $form;
        #
        # so you only need to do the following...

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

        if ( $form->submitted_and_valid ) {
            do_something();
        }
    }

    sub quux : Local : FormMethod('load_form') {
        my ( $self, $c ) = @_;

        # using the FormMethod attribute with an argument is equivalent to:
        #
        # my $form = $self->form;
        #
        # $form->populate( $c->load_form );
        #
        # $form->process;
        #
        # $c->stash->{form} = $form;
        #
        # so you only need to do the following...

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

        if ( $form->submitted_and_valid ) {
            do_something();
        }
    }

    sub load_form {
        my ( $self, $c ) = @_;

        # Automatically called by the above FormMethod('load_form') action.
        # Called as a method on the controller object, with the context
        # object as an argument.

        # Must return a hash-ref suitable to be fed to $form->populate()
    }

You can also use specially-named actions that will only be called under certain circumstances.

    sub edit : Chained('group') : PathPart : Args(0) : FormConfig { }

    sub edit_FORM_VALID {
        my ( $self, $c ) = @_;

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

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

        $c->response->redirect( $c->uri_for( '/group', $group->id ) );
    }

    sub edit_FORM_NOT_SUBMITTED {
        my ( $self, $c ) = @_;

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

        $form->model->default_values( $group );
    }

METHODS

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

        my $form = $self->form;
    }

SPECIAL ACTION NAMES

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

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

        $c->detach('/unauthorised') unless $c->user->can_edit( $group );

        if ( $form->submitted_and_valid ) {
            $form->model->update( $group );

            $c->response->redirect( $c->uri_for('/group', $group->id ) );
            return;
        }
        elsif ( !$form->submitted ) {
            $form->model->default_values( $group );
        }

        $self->_add_breadcrumbs_nav( $c, $group );
    }

Instead becomes...

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

        $c->detach('/unauthorised') unless $c->user->can_edit(
            $c->stash->{group}
        );
    }

    sub edit_FORM_VALID {
        my ( $self, $c ) = @_;

        my $group = $c->stash->{group};

        $c->stash->{form}->model->update( $group );

        $c->response->redirect( $c->uri_for('/group', $group->id ) );
    }

    sub edit_FORM_NOT_SUBMITTED {
        my ( $self, $c ) = @_;

        $c->stash->{form}->model->default_values(
            $c->stash->{group}
        );
    }

    sub edit_FORM_RENDER {
        my ( $self, $c ) = @_;

        $self->_add_breadcrumbs_nav( $c, $c->stash->{group} );
    }

For any action method that uses a "Form", "FormConfig" or "FormMethod" attribute, you can add extra methods that use the naming conventions below.

These methods will be called after the original, plainly named action method.

CUSTOMIZATION

    $c->config( 'Controller::HTML::FormFu' => \%my_values );

    # or

    MyApp->config( 'Controller::HTML::FormFu' => \%my_values );

    # or, in myapp.conf

    <Controller::HTML::FormFu>
        default_action_use_path 1
    </Controller::HTML::FormFu>

    action: /foo/bar
    called uri contains: /foo/bar/1

    # default_action_use_name => 1 leads to:
    $form->action = /foo/bar

    # default_action_use_path => 1 leads to:
    $form->action = /foo/bar/1

    <Controller::HTML::FormFu>
        <model_stash>
            schema MySchema
        </model_stash>
    </Controller::HTML::FormFu>

    $form->stash->{context};

DISCONTINUED CONFIG SETTINGS

CAVEATS

When using the "FormConfig" and "FormMethod" action attributes, if you make any modifications to the form, such as adding or changing it's elements, you must call $form->process before rendering the form.

AUTHORS

• Carl Franks <cpan@fireartist.com>
• Nigel Metheringham <nigelm@cpan.org>
• Dean Hamstead <dean@bytefoundry.com.au>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

SUPPORT

  perldoc Catalyst::Controller::HTML::FormFu

  git clone https://github.com/FormFu/Catalyst-Controller-HTML-FormFu.git

CONTRIBUTORS

• Aran Deltac <aran@ziprecruiter.com>
• bricas <brian.cassidy@gmail.com>
• dandv <ddascalescu@gmail.com>
• fireartist <fireartist@gmail.com>
• lestrrat <lestrrat+github@gmail.com>
• marcusramberg <marcus.ramberg@gmail.com>
• mariominati <mario.minati@googlemail.com>
• Moritz Onken <1nd@gmx.de>
• Moritz Onken <onken@netcubed.de>
• Nigel Metheringham <nm9762github@muesli.org.uk>
• omega <andreas.marienborg@gmail.com>
• Petr Písař <ppisar@redhat.com>