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.