NAME
Validation::Class::Plugin::FormFields - HTML Form Field Renderer for
Validation::Class
VERSION
version 0.36
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');
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 much 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. The rendered elements will always be returned as
an array.
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);
radiobutton
The radiobutton method initializes an HTML::Element radiobutton object
to represent a radio-button 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->radiobutton('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. The rendered elements will always be
returned as an array.
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);
# or, in keeping with convention, ...
# to include a default state, i.e. an initial option with an blank value
$self->selectbox('field_name', placeholder => 'Choose One');
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.