# NAME

Validation::Class::Plugin::FormFields - Validation::Class HTML Form Field Renderer

# VERSION

version 0.21

# SYNOPSIS

    package MyApp::Validation;
    

    use Validation::Class;
    

    load {
        plugins => ['FormFields']
    };
    

    # a validation rule
    

    field 'login'  => {
        label      => 'User Login',
        error      => 'Login invalid.',
        required   => 1,
        validation => sub {
            my ($self, $this_field, $all_params) = @_;
            return $this_field->{value} eq 'admin' ? 1 : 0;
        }
    };
    

    # a validation rule
    

    field 'password'  => {
        label         => 'User Password',
        error         => 'Password invalid.',
        required      => 1,
        validation    => sub {
            my ($self, $this_field, $all_params) = @_;
            return $this_field->{value} eq 'pass' ? 1 : 0;
        }
    };
    

    # elsewhere in the application
    

    package main ;
    

    my $input = MyApp::Validation->new(params => $params);
    

    $input->validate('login', 'password');
    

    my $form = $input->form_fields; # returns a V::C::P::FormFields object
    

    print $form->render_field('login', 'text');
    print $form->render_field('password', 'password');

# DESCRIPTION

More importanly than explaining what this plugin is, I will first proclaim what
it IS NOT. Validation::Class::Plugin::FormFields is not an HTML form construction
kit, nor is it a one-size-fits-all form handling machine, ... it is however a
plugin for use with your [Validation::Class](http://search.cpan.org/perldoc?Validation::Class) class that allows you to render
HTML form fields based on your defined validation fields.

Why render fields individually and not the entire form?
Form generation is pretty evil (IMHO), whereas the generating of HTML elements
is alot less evil and definately alot more rational. Full-blown form generation
locks you in a box offering only slight convenience and major headaches when you
need anything more than the out-of-the-box generated output.

Obviously we have to generate some output or this plugin would be a ridiculous
waste of space, that said however, the generated HTML is sensible and consistent
and allows easy CSS styling and JavaScript manipulation.

For more information about defining fields (validation rules), feel free to look
over [Validation::Class](http://search.cpan.org/perldoc?Validation::Class). 

# DISCLAIMER

__EXPERIMENTAL__, Validation::Class::Plugin::FormFields is super new and is
currently only a proof-of-concept. Though the current API is not expected to
change much, I can't make any promises.

# ATTRIBUTES

## field_templates

The field_templates attribute holds a hashref of field template filenames and
their shortnames.

## field_templates_location

The field_templates_location attribute is the absolute location to the folder
where the field templates are stored.

# METHODS

## field_template

The field_template method returns the complete path and filename of the
specified template.

    my $input = MyApp::Validation->new(params => $params);
    my $template = $input->stash('form_fields')->()->field_template('radio');

## render_field

The render_field method renders an HTML block based on the specified arguments
passed to it. This method takes three arguments, the name of the field, type of
element to render, and an optional hashref to further configure the rendering
process.

The render_field method render an HTML control block and not just a single
HTML element. The HTML control block will always be a div element which wraps
the HTML form input fields.

    package MyApp::Validation;
    

    use Validation::Class;
    

    load {
        -plugins => ['FormFields']
    };
    

    field 'login'  => {
        label      => 'User Login',
        error      => 'Login invalid.',
        required   => 1,
        validation => sub {
            my ($self, $this_field, $all_params) = @_;
            return $this_field->{value} eq 'admin' ? 1 : 0;
        }
    };
    

    field 'password'  => {
        label         => 'User Password',
        error         => 'Password invalid.',
        required      => 1,
        validation    => sub {
            my ($self, $this_field, $all_params) = @_;
            return $this_field->{value} eq 'pass' ? 1 : 0;
        }
    };
    

    field 'remember'  => {
        label         => 'Remember Authentication',
        error         => 'Remember authentication invalid.',
        options       => 'Yes, No'
    };
    

    # elsewhere is the application
    

    package main ;
    

    my $input = MyApp::Validation->new(params => $params);
    my $form  = $input->form_fields;
    

    my $user_field  = $form->render_field('login', 'text');
    my $pass_field  = $form->render_field('password', 'password');
    

    my $remember_me = $form->render_field('remember', 'check', {
        select  => 'Yes',
        options => [
            { text => 'Yes', value => 'Yes' },
            { text => 'No', value => 'No' },
        ]
    });

The following is a list of HTML elements that the render_field method can
produce along with their syntax and options.

### check

The check option instructs the render_field method to produce a checkbox or
checkbox group depending on whether you supply an arrayref of options.

    # renders a single checkbox 
    my $checkbox = $form->render_field($field, 'check');

    # renders a checkbox group
    my $checkbox = $form->render_field($field, 'check', {
        select  => [@default_value],
        options => [
            { text => '...', value => '...' },
            { text => '...', value => '...' },
        ]
    });

### file

The file option instructs the render_field method to produce a file upload
form field.

    # renders a single file element
    my $upload = $form->render_field($field, 'file');

### hidden

The hidden option instructs the render_field method to produce a hidden form
field.

    # renders a single hidden element
    my $hidden = $form->render_field($field, 'hidden');

### password

The password option instructs the render_field method to produce a
password-protected input form field.

    # renders a single password element
    my $password = $form->render_field($field, 'password');

### radio

The radio option instructs the render_field method to produce a radio button or
radio button group depending on whether you supply an arrayref of options.

    # renders a single radio button
    my $radio = $form->render_field($field, 'radio');

    # renders a radio button group
    my $radio = $form->render_field($field, 'radio', {
        select  => $default_value,
        options => [
            { text => '...', value => '...' },
            { text => '...', value => '...' },
        ]
    });

### select

The select option instructs the render_field method to produce a selectbox also
known as a dropdown box.

    # renders a single selectbox
    my $selectbox = $form->render_field($field, 'selectbox');

### multi_select

The multi_select option instructs the render_field method to produce a selectbox
configured to allow the selection of multiple values.

    # renders a multi selectbox or combobox
    my $combobox = $form->render_field($field, 'multi_select', {
        select  => [@default_values],
        options => [
            { text => '...', value => '...' },
            { text => '...', value => '...' },
        ]
    });

### text

The text option instructs the render_field method to produce a standard
text input form field.

    # renders a single textbox
    my $text = $form->render_field($field, 'text');

The HTML5 specification support an array of input types. You can cast the
standard text input element into other type by specifying a type parameter as
follows:

    # renders an email textbox
    my $email = $form->render_field($field, 'text', { type => 'email' });
    

    # renders a url textbox
    my $website = $form->render_field($field, 'text', { type => 'url' });
    

    ...

### textarea

The textarea option instructs the render_field method to produce a textarea for
multi-line text input.

    # renders a single textarea
    my $textarea = $form->render_field($field, 'textarea');

# HTML FORM FIELD TEMPLATES

The HTML form field elements are rendered via TT (template-toolkit) templates.
The actual template files are embedded in this distribution however you may copy
them to your current working directory by issuing the following command at the
command-line:

    $ vcformfields [<path>]

Once copied and modified to your liking, specify the current working directory
in your validation class instance as follows:

    my $form = MyVal::Validation->new;
       $form->field_templates_location($location);

# AUTHOR

Al Newkirk <awncorp@cpan.org>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by awncorp.

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