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

VERSION
    version 0.34

SYNOPSIS
        # THIS PLUGIN IS UNTESTED AND MAY BE SUBJECT TO DESIGN CHANGES!!!

        use Validation::Class::Simple;

        my $rules = Validation::Class::Simple->new(
            fields => {
                username => { required => 1 },
                password => { required => 1 },
                remember => { options  => 'remember' },
                notify   => { options  => 'notify' }
            }
        );

        my $fields = $rules->plugin('form_fields');

        printf "%s\n", $fields->textbox('username', placeholder => 'Username');
        printf "%s\n", $fields->lockbox('password', placeholder => 'Password');

        printf "%s Remember Me?\n", $fields->checkbox('remember');
        printf "%s Notify Me?\n",   $fields->checkbox('notify');

DESCRIPTION
    Validation::Class::Plugin::FormFields is a plugin for Validation::Class
    which can leverage your validation class field definitions to render
    HTML form elements. Please note that this plugin is intentionally
    lacking in sophistication and try to take as few liberties as possible.

RATIONALE
    Validation::Class::Plugin::FormFields is not an HTML form handler, nor
    is it an HTML form builder, renderer, construction kit, or framework.
    Why render fields individually and not the entire form? Form handling is
    a heavily opinionated subject and this plugin reflects the following
    perspective.

    HTML form generation, done literally, has too many contraints and
    considerations to ever be truly ideal. Consider the following, it's been
    tried many many times before, it's never pretty, too many conflicting
    contexts (css, js, security and identification), css wants the form
    configured a certain way for styling purposes, js wants the form
    configured a certain way for introspection purposes, the app wants the
    form configured a certain way for processing purposes, etc.

    So why do we continue to try? HTML forms are like werewolves and
    developers love silver bullets, but bullets are actually made out of
    lead, not silver. So how do you kill werewolves with lead? Hint, not by
    shooting them obviously.

    I'd argue that we never really wanted complete form rendering anyway,
    what we actually wanted was a simple way to reduce the tedium and
    repetitiveness that comes with creating HTML form elements and handling
    submission and validation of the associated data. We keep getting it
    wrong because we keep trying to build on top of the same misconceptions.

    So maybe we should backup a bit and try something different. The
    generating of HTML elements is alot less constrained and definately much
    more straight-forward.

METHODS
  checkbox
    The checkbox method initializes an HTML::Element checkbox object to
    represent a checkbox in an HTML form. The value and checked attributes
    will be automatically included based on the state of the validation
    class prototype; determined based on the existence of the following: a
    parameter value, a field value, or field default value. Note that if
    multiple values exist, only the first value will be used.

        $self->checkbox('field_name', %attributes_list);

  checkgroup
    The checkgroup method initializes an array of HTML::Element checkbox
    objects to represent a list of checkboxes in an HTML form. The value and
    checked attributes will be automatically included based on the state of
    the validation class prototype; determined based on the existence of the
    following: a parameter value, a field value, or field default value.

    Please note that rendering is based-on the options directive and each
    checkbox is appended with a span element containing the option's key or
    value for each individual option. Please see the "options directive" for
    additional information.

        field_name => {
            options => [
                'Choice 1',
                'Choice 2',
                'Choice 3',
            ]
        }

        # or

        field_name => {
            options => [
                '1|Choice 1',
                '2|Choice 2',
                '3|Choice 3',
            ]
        }

        # then

        $self->checkgroup('field_name', %attributes_list);

  element
    The element method returns the pre-configured HTML::Element object(s)
    for the given field, or the last field operated on if no argument is
    passed.

        $self->element('field_name');

  hidden
    The hidden method initializes an HTML::Element hidden-field object to
    represent a hidden field in an HTML form. The value attribute will be
    automatically included based on the state of the validation class
    prototype; determined based on the existence of the following: a
    parameter value, a field value, or field default value. Note that if
    multiple values exist, only the first value will be used.

        $self->hidden('field_name', %attributes_list);

  lockbox
    The lockbox method is an alias for the password method which initializes
    an HTML::Element password-field object to represent a password in an
    HTML form. The value attribute will be automatically included based on
    the state of the validation class prototype; determined based on the
    existence of the following: a parameter value, a field value, or field
    default value. Note that if multiple values exist, only the first value
    will be used.

        $self->lockbox('field_name', %attributes_list);

  multiselect
    The multiselect method initializes an HTML::Element selectbox object to
    represent a selectbox with a list of options where multiple options may
    be selected in an HTML form. The value and selected attributes will be
    automatically included based on the state of the validation class
    prototype; determined based on the existence of the following: a
    parameter value, a field value, or field default value.

    Please note that rendering is based-on the options directive and each
    option element's contents contains the option's key or value for each
    individual option. Please see the "options directive" for additional
    information.

        field_name => {
            options => [
                'Choice 1',
                'Choice 2',
                'Choice 3',
            ]
        }

        # or

        field_name => {
            options => [
                '1|Choice 1',
                '2|Choice 2',
                '3|Choice 3',
            ]
        }

        # then

        $self->multiselect('field_name', %attributes_list);

  password
    The password method initializes an HTML::Element password-field object
    to represent a password in an HTML form. The value attribute will be
    automatically included based on the state of the validation class
    prototype; determined based on the existence of the following: a
    parameter value, a field value, or field default value. Note that if
    multiple values exist, only the first value will be used.

        $self->password('field_name', %attributes_list);

  radiogroup
    The radiogroup method initializes an array of HTML::Element radiobutton
    objects to represent a list of radiobuttons in an HTML form. The value
    and checked attributes will be automatically included based on the state
    of the validation class prototype; determined based on the existence of
    the following: a parameter value, a field value, or field default value.

    Please note that rendering is based-on the options directive and each
    radiobutton is appended with a span element containing the option's key
    or value for each individual option. Please see the "options directive"
    for additional information.

        field_name => {
            options => [
                'Choice 1',
                'Choice 2',
                'Choice 3',
            ]
        }

        # or

        field_name => {
            options => [
                '1|Choice 1',
                '2|Choice 2',
                '3|Choice 3',
            ]
        }

        # then

        $self->radiogroup('field_name', %attributes_list);

  selectbox
    The selectbox method initializes an HTML::Element selectbox object to
    represent a selectbox with a list of options in an HTML form. The value
    and selected attributes will be automatically included based on the
    state of the validation class prototype; determined based on the
    existence of the following: a parameter value, a field value, or field
    default value.

    Please note that rendering is based-on the options directive and each
    option element's contents contains the option's key or value for each
    individual option. Please see the "options directive" for additional
    information.

        field_name => {
            options => [
                'Choice 1',
                'Choice 2',
                'Choice 3',
            ]
        }

        # or

        field_name => {
            options => [
                '1|Choice 1',
                '2|Choice 2',
                '3|Choice 3',
            ]
        }

        # then

        $self->selectbox('field_name', %attributes_list);

  textarea
    The textarea method initializes an HTML::Element textarea-field object
    to represent a textarea in an HTML form. The element's contents will be
    automatically included based on the state of the validation class
    prototype; determined based on the existence of the following: a
    parameter value, a field value, or field default value. Note that if
    multiple values exist, only the first value will be used.

        $self->textarea('field_name', %attributes_list);

  textbox
    The textbox method initializes an HTML::Element textbox object to
    represent a textbox in an HTML form. The value attribute will be
    automatically included based on the state of the validation class
    prototype; determined based on the existence of the following: a
    parameter value, a field value, or field default value. Note that if
    multiple values exist, only the first value will be used.

        $self->textbox('field_name', %attributes_list);

  render
    The render method renders-and-returns pre-configured HTML::Element
    object(s) for the given field, or the last field operated on if no
    argument is passed. This method is called automatically when the object
    is used in scalar context.

        $self->render('field_name');

AUTHOR
    Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Al Newkirk.

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

