NAME

HTML::Field - Generation of HTML form elements

SYNOPSIS

 use HTML::Field;

 ########## Creation of Field objects ##############
 
 # A text field:
 my $field1 = HTML::Field->new('Textfield',
                  name      => 'fieldname',
                  value     => 'current value',
                  default   => 'default value',
                  size      => 15,
                  maxlength => 15 );

 # A Pasword field (has the same attributes as 'Textfield'):
 my $field2 = HTML::Field->new('Passwd',
                  name      => 'fieldname',
                  value     => 'current value',
                  default   => 'default value',
                  size      => 15,
                  maxlength => 15 );
 
 # A hidden field:
 my $hidden = HTML::Field->new('Hidden',
                  name      => 'sid',
                  value     => 'cgiasf25k',
                  default   => undef );
 
 # A text area:
 my $area = HTML::Field->new('Textarea',
                  name      => 'address',
                  cols      => 40,
                  rows      => 4 );
 
 # A 'select' tag. Options are given in an array reference; labels are  
 # given in a hash keyed by the options: 
 my $select = HTML::Field->new('Select',
                  name      => 'select_color',
                  options   => [qw(red yellow brown)],
                  default   => 'red',
                  labels    => {red    => 'Color of apples',
                                yellow => 'Color of mangos!',
                                brown  => 'Color of chocolate'},
                  multiple  => undef,  # Multiple is either true or false
                  size      => 1 );    # Size of select box
                  
 # A radio button. Note that it will generate the HTML for all of its
 # options, and those will be named as 'name_option'
 my $radio_buttons = HTML::Field->new('Radio',
                  name      => 'Flavors',
                  options   => [qw(Lemon Strawberry Grapefruit)],
                  default   => 'Grapefruit' );

 # A single checkbox:
 my $checkbox = HTML::Field->new('Checkbox', 
                  name      => 'Additional',
                  option    => 'Strawberry',
                  default   => 1,
                  read_only_tags => { true => 'X', false => 'o'});
                  
 # Render editable HTML
 my ($key, $value) = $field->editable_html;
 
 # Render read-only value
 ($key, $value) = $field->readonly_html;
 
 # Render editable HTML for a new element
 ($key, $value) = $field->creation_html;
 
 # Set a field's value from a CGI object, hash reference or scalar:
 my $value = $field->value($cgi);
 
 # or, get the filed's value:
 $value = $field->value;
 
 
 # The 'read_only_tags' attribute sets the representation of a
 # check box or of radio buttons for a 'read only' rendering. 
 # This feature can be used to load different images to represent
 # 'checked' radio buttons or check boxes.
 
 # Primary Key text field:
 my $field1 = HTML::Field->new('Textfield',
                  name        => 'login',
                  size        => 15,
                  maxlength   => 15,
                  primary_key => 1 );
                  
 # When a text field is marked as 'primary' key, then
 # it will not be editable once it has a value. This means that if you 
 # are displaying an empty form this will be an editable text field, 
 # but if you are displaying a database record for edition, then this 
 # field will not be editable and it will also be present as a hidden
 # field in order to get sent back to the script.
 
 # Primary key autogenerated by the database:
 my $serial = HTML::Field->new('Textfield',
                  name        => 'company_id',
                  size        => 4,
                  maxlength   => 4,
                  auto        => 1 );
                  
 # The same as above applies if the field value is generated by the 
 # database. In that case, the  value will never be editable; if the 
 # field has no value then a place holder will be returned instead.

DESCRIPTION

HTML::Field objects are able to read their values from CGI objects, hash references or plain scalars and then render those values as HTML fields or simple read-only HTML. They are meant to ease the interface between CGI, databases and templates.

IMPORTANT NOTE: This module does not validate the values of any HTML attributes that you supply.

See HTML::FieldForm for a class that works on sets of HTML::Fields.

COMMON ATTRIBUTES

Common functional attributes

There are three functional attributes for all Field objects: name, value and default. By functional, I mean that these attributes have other uses than solely appearing in HTML. value and default have accessor/mutators named after them; name is read-only and must be set during creation.

`name`

Of the three common, functional attributes only name is required. name will be used for the following important things:

1. To look for the field value in a hash or a CGI object
2. As the key in the hashes returned by the html methods
3. As the name of the html tags produced

So, if you are using HTML::Template, it is adviceable to name the parameters of your template the same as the fields you will use to populate it.

`value` and `default`

These two attributes define the value of the Field objects in different stages of their existance. If you include a default for an object, it will be the value that will be used since object creation until it is explicitly changed by value. The reset_value method will set value equal to default.

You can feed value with a hash reference, a CGI object or a scalar value to set the value of a given field:

 $field->value($cgi);
 $field->value($hash_ref);
 $field->value(4);

Common HTML Attributes

Several HTML attributes can be used within all field tags. There are two kinds of HTML attributes: Those which can take a value and those which are just true or false. For those which can have a value, their value can be any scalar and it will simply be inculded in the field tag.

All of these attributes may be set during object creation and also using their accessor/mutator (implemented via AUTOLOAD).

The following HTML attributes may be used with all of the HTML::Field classes:

accesskey
id
title
class
style
lang
dir
tabindex
disabled (Boolean)
readonly (Boolean)

Each HTML::Field class may have its own, particular attributes. See below.

COMMON METHODS

Besides the accessor/mutator methods explained above, there are three methods common to every Field object:

$field->reset_values

Makes value equal to default.

%hash = $field->editable_html

The returned hash will have the field's name as key and its HTML field tag as value. It returns a hash because this way it is simpler to include it in a template (think HTML::Template). In this case, you can use it like this:

 $template->param($field->editable_html);

%hash = $field->readonly_html

Same as above, except that the HTML will not be a form tag but only a read-only HTML representation of the field's value. Usually this read-only HTML is simply the value of the field.

For the checkboxes and radio buttons, it is possible to have images or any other mark up to display 'true' and 'false' states for reading via the readonly_tags attribute; you can see it in the SYNOPSIS. This attribute has its accessor/mutator of the same name.

%hash = $field->creation_html

This method will return an empty HTML field for edition. Normally this method should be used when creating a new record in a database, as it will allow for the edition of fields marked as 'primary_key' (not for 'auto'). See the next section for an extended explanation.

ATTRIBUTES `primary_key` and `auto`

If a form is displayed for the entry of a new record, then there are two scenarios regarding primary keys:

auto -- Primary key is generated by the database or application

In this case the system generates a value for the primary key prior to its insertion in the database. This value will not exist when the empty form is served to the client for the first time, so it should not be included. However, it will exist and is needed if the record is requested for updating. In this case it will be sent in a non-editable form, followed by a hidden field (in the case of text fields). Think of using a hidden field for this case.

primary_key -- Primary key is entered by the user

If the primary key of a record will be supplied by the user, then the field must be empty and editable when the form is first displayed. Once the record exists the primary key will be sent in a read-only form followed by a hidden field. This way the primary key will be present in the data sent back to the server for updating the database.

Note that because the field needs to be editable for record creation, a hidden field cannot be marked as primary key.

In summary, calling creation_html on a field marked as primary_key will display an editable field. Calling editable_html will return a read-only value followed with a hidden field.

Calling creation_html on a field marked as auto will only display an HTML comment as a marker. Calling editable_html will display a hidden field instead, and in the case of a text field, it will also display its value.

You can only mark text fields as 'primary_key'; text and hidden fields support 'auto'.

SUBCLASSES AND THEIR PARTICULAR ATTRIBUTES AND METHODS

HTML::Field::Textfield

ATTRIBUTES

These attributes are optional. They have accessor/mutator methods (via AUTOLOAD).

size
maxlength
primary_key (Not an HTML attribute; see explanation above)
auto (Not an HTML attribute; see explanation above)

HTML::Field::Hidden

Fields of this class must have a value when issueing editable HTML or they will raise an exception.

These fields may be marked as auto, but not as primary_key.

auto (Not an HTML attribute; see explanation above)

HTML::Field::Password

ATTRIBUTES

These attributes are optional. They have accessor/mutator methods (via AUTOLOAD).

size
maxlength

HTML::Field::Textarea

ATTRIBUTES

These attributes are optional. They have accessor/mutator methods (via AUTOLOAD).

cols
rows
wrap

HTML::Field::Checkbox

This class is useful to implement single checkboxes; in other words, checkboxes that have their own name.

ATTRIBUTES

These attributes are optional. They have accessor/mutator methods (via AUTOLOAD).

readonly_tags

This attribute can take a hash with the keys 'true' and 'false', which should point to read-only representations of checked (true) or not checked (false) fields. For example:

 $field->readonly_tags(
        true  => '<img src="checked.png"     alt="Checked"/>',
        false => '<img src="not_checked.png" alt="Not checked"/>',
 );

Default is '+' for true and '-' for false.

HTML::Field::Select

ATTRIBUTES

These attributes have accessor/mutator methods (via AUTOLOAD).

size -- Optional
multiple -- Optional (true or false only)
options -- Required: Array reference of options.
labels -- Required: labels will accept a hash of labels keyed by option.

HTML::Field::Radio

Class to create radio button fields. A single object will generate as many radio buttons as options it has. These buttons will be named like this:

 field_option

So, following the example in the synopsis, we would have: Flavors_Lemon, Flavors_Strawberry, and Flavors_Grapefruit.

ATTRIBUTES

These attributes have accessor/mutator methods (via AUTOLOAD).

options -- Required: Array reference of options.
readonly_tags: See HTML::Field::Checkbox for an explanation.

AUTHOR

Julio Fraire, <julio.fraire@gmail.com<gt>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

To install HTML::Field, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTML::Field

CPAN shell

perl -MCPAN -e shell
install HTML::Field

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

COMMON ATTRIBUTES

Common functional attributes

name

value and default

Common HTML Attributes

COMMON METHODS

ATTRIBUTES primary_key and auto

SUBCLASSES AND THEIR PARTICULAR ATTRIBUTES AND METHODS

HTML::Field::Textfield

ATTRIBUTES

HTML::Field::Hidden

HTML::Field::Password

ATTRIBUTES

HTML::Field::Textarea

ATTRIBUTES

HTML::Field::Checkbox

ATTRIBUTES

HTML::Field::Select

ATTRIBUTES

HTML::Field::Radio

ATTRIBUTES

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

`name`

`value` and `default`

ATTRIBUTES `primary_key` and `auto`