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

VERSION
    version 0.0.5

SYNOPSIS
        package MyApp::Validation;
        
    use Validation::Class; __PACKAGE__
            ->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 is the application
        package main ;
        
    my $form = MyApp::Validation->new(params => $params);
        
    $form->validate('login', 'password');
        
    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 and/or HTML element construction kit, nor is it a
    one-size-fits-all form handling machine, it is however a plugin for use
    with your Validation::Class class that allows you to render HTML form
    fields based on your defined validation fields in their given states.

    So why why render fields individually and not the entire form (fields
    collection). Form generation is pretty evil IMO, whereas the generating
    of HTML elements is 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.

    Render elements indivually, obviously we have to generate some output or
    this plugin would be a ridiculous waste of space, however .. the
    generated HTML is sensible and consistent to allow easy CSS styling and
    JavaScript manipulations.

    Ever tried to add an HTML5 <button>Click Me</button> or Horizontal Rule
    <hr/> to your form that was generated by that form rendering package you
    used to use ...? Don't render forms with code, Take back control of your
    controls.

    For more information about defining fields (validation rules), feel free
    to look over 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 $form = MyApp::Validation->new(params => $params);
        my $template = $form->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; __PACKAGE__
            ->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 $form = MyApp::Validation->new(params => $params);
        
    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');

   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
    (template-toolkit). 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:

        $ Validation-Class-Plugin-FormField-Templates [<path>]

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

        $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.