NAME
HTML::FormBuilder - A Multi-part HTML form
SYNOPSIS
#define a form
my $form = HTML::FormBuilder->new(
data =>{id => 'formid',
class => 'formclass'},
classes => {row => 'rowdev'})
#create fieldset
my $fieldset = $form->add_fieldset({id => 'fieldset1});
#add field
$fieldset->add_field({input => {name => 'name', type => 'text', value => 'Join'}});
#set field value
$form->set_field_value('name', 'Omid');
#output the form
print $form->build;DESCRIPTION
Object-oriented module for displaying an HTML form.
Overview of Form's HTML structure
The root of the structure is the <form> element and follow by multiple <fieldset> elements.
In each <fieldset>, you can create rows which contain label, different input types, error message and comment <p> element.
Please refer to "A full sample result"
Attributes
data
The form attributes. It should be a hashref.
classes
The form classes. It should be a hashref. You can customize the form's layout by the classes. The class names used are:
fieldset_group
no_stack_field_parent
row_padding
fieldset_footer
comment
row
extra_tooltip_container
backbutton
required_asterisk
inputtrailing
label_column
input_column
hide_mobilelocalize
The subroutine ref which can be called when translate something like 'Confirm'. The default value is no translating.
fieldsets
The fieldsets the form have.
Methods
new
my $form = HTML::FormBuilder->new(
data =>{id => 'formid',
class => 'formclass'},
classes => {row => 'rowdev'})The id is required for the form.
add_fieldset
my $fieldset = $form->add_fieldset({id => 'fieldset1});the parameter is the fieldset attributes. It will return the fielset object.
add_field
$form->add_field(0, {input => {name => 'name', type => 'text', value => 'Join'}});The parameter is the fieldset index to which you want to add the field and the field attributes.
build
print $form->build;the data in the $form will be changed when build the form. So you cannot get the same result if you call build twice.
BUILDARGS
build_confirmation_button_with_all_inputs_hidden
csrftoken
get_field_error_message
get_field_value
set_field_error_message
set_field_value
Cookbook
a full sample
# Before create a form, create a classes hash for the form
my $classes = {comment => 'comment', 'input_column' => 'column'};
# And maybe you need a localize function to translate something
my $localize = sub {i18n(shift)};
# First, create the Form object. The keys in the HASH reference is the attributes of the form
$form_attributes => {'id' => 'id_of_the_form',
'name' => 'name_of_the_form',
'method' => 'post', # or get
'action' => 'page_to_submit',
'header' => 'My Form',
'localize' => $localize,
'classes' => $classes,
}; #header of the form
my $form = HTML::FormBuilder->new(data => $form_attributes, classes => $classes, localize => $localize);
#Then create fieldset, the form is allow to have more than 1 fieldset
#The keys in the HASH reference is the attributes of the fieldset
$fieldset_attributes => {'id' => 'id_of_the_fieldset',
'name' => 'name_of_the_fieldset',
'class' => 'myclass',
'header' => 'User details', #header of the fieldset
'comment' => 'please fill in', #message at the top of the fieldset
'footer' => '* - required',}; #message at the bottom of the fieldset
};
my $fieldset = $form->add_fieldset($fieldset_attributes);
####################################
#Create the input fields.
####################################
#When creating an input fields, there are 4 supported keys.
#The keys are label, input, error, comment
# Label define the title of the input field
# Input define and create the actual input type
# In input fields, you can defined a key 'heading', which create a text before the input is displayed,
# however, if the input type is radio the text is behind the radio box
# Error message that go together with the input field when fail in validation
# Comment is the message added to explain the input field.
####################################
###Creating a input text
####################################
my $input_text = {'label' => {'text' => 'Register Name', for => 'name'},
'input' => {'type' => 'text', 'value' => 'John', 'id' => 'name', 'name' => 'name', 'maxlength' => '22'},
'error' => { 'id' => 'error_name' ,'text' => 'Name must be in alphanumeric', 'class' => 'errorfield hidden'},
'comment' => {'text' => 'Please tell us your name'}};
####################################
###Creating a select option
####################################
my @options;
push @options, {'value' => 'Mr', 'text' => 'Mr'};
push @options, {'value' => 'Mrs', 'text' => 'Mrs'};
my $input_select = {'label' => {'text' => 'Title', for => 'mrms'},
'input' => {'type' => 'select', 'id' => 'mrms', 'name' => 'mrms', 'options' => \@options},
'error' => {'text' => 'Please select a title', 'class' => 'errorfield hidden'}};
####################################
###Creating a hidden value
####################################
my $input_hidden = {'input' => {'type' => 'hidden', 'value' => 'John', 'id' => 'name', 'name' => 'name'}};
####################################
###Creating a submit button
####################################
my $input_submit_button = {'input' => {'type' => 'submit', 'value' => 'Submit Form', 'id' => 'submit', 'name' => 'submit'}};
###NOTES###
Basically, you just need to change the type to the input type that you want and generate parameters with the input type's attributes
###########################################################
###Having more than 1 input field in a single row
###########################################################
my $input_select_dobdd = {'type' => 'select', 'id' => 'dobdd', 'name' => 'dobdd', 'options' => \@ddoptions};
my $input_select_dobmm = {'type' => 'select', 'id' => 'dobmm', 'name' => 'dobmm', 'options' => \@mmoptions};
my $input_select_dobyy = {'type' => 'select', 'id' => 'dobyy', 'name' => 'dobyy', 'options' => \@yyoptions};
my $input_select = {'label' => {'text' => 'Birthday', for => 'dobdd'},
'input' => [$input_select_dobdd, $input_select_dobmm, $input_select_dobyy],
'error' => {'text' => 'Invalid date.'}};
#Then we add the input field into the Fieldset
#You can add using index of the fieldset
$fieldset->add_field($input_text);
$fieldset->add_field($input_select);
$fieldset->add_field($input_submit_button);
###########################################################
### Field value accessors
###########################################################
$form->set_field_value('name', 'Omid');
$form->get_field_value('name'); # Returns 'Omid'
###########################################################
### Error message accessors
###########################################################
$form->set_field_error_message('name', 'Your name is not good :)');
# or
$form->set_field_error_message('error_name', 'Your name is not good :)');
$form->get_field_error_message('name'); # Return 'Your name is not good :)'
# or
$form->get_field_error_message('error_name'); # Return 'Your name is not good :)'
#Finally, we output the form
print $form->build();A full sample result
<form id="onlineIDForm" method="post" action="">
<fieldset id="fieldset_one" name="fieldset_one" class="formclass">
<div>
<label for="name">Register Name</label>
<em>:</em>
<input type="text" value="John" id="name" name="name">
<p id = "error_name" class="errorfield hidden">Name must be in alphanumeric</p>
<p>Please tell us your name</p>
</div>
<div>
<label for="mrms">Title</label>
<em>:</em>
<select id="mrms" name="mrms">
<option value="Mr">Mr</option>
<option value="Mrs">Mrs</option>
</select>
<p class="errorfield hidden">Please select a title</p>
</div>
<div>
<label for="dob">Birthday</label>
<em>:</em>
<select id="dobdd" name="dobdd">
<option value="1">1</option>
<option value="2">2</option>
</select>
<select id="dobmm" name="dobmm">
<option value="1">Jan</option>
<option value="2">Feb</option>
</select>
<select id="dobyy" name="dobyy">
<option value="1980">1980</option>
<option value="1981">1981</option>
</select>
<p class="errorfield hidden">Invalid date</p>
</div>
<div>
<input type="submit" value="Submit Form" id="submit" name="submit">
</div>
</fieldset>
</form>How to create a form with validation
Please refer to <HTML::FormBuilder::Validation>
CROSS SITE REQUEST FORGERY PROTECTION
read <HTML::FormBuilder::Validation> for more details
AUTHOR
Chylli mailto:chylli@binary.com
INHERITED METHODS
CONTRIBUTOR
Fayland Lam mailto:fayland@binary.com
Tee Shuwn Yuan mailto:shuwnyuan@binary.com