Al Newkirk > Validation-Class-Plugin-FormFields-0.34 > Validation::Class::Plugin::FormFields

Download:
Validation-Class-Plugin-FormFields-0.34.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.34   Source   Latest Release: Validation-Class-Plugin-FormFields-7.900022

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.

syntax highlighting: