NAME

HTML::Formulate - module for producing/rendering HTML forms

SYNOPSIS

# Simple employee create form
$f = HTML::Formulate->new({
   fields => [ qw(firstname surname email position) ],
   required => [ qw(firstname surname) ],
});
print $f->render;

outputs:

<form method="post">
<table cellpadding="2">
<tr><th style="color:blue"><span class="required">Firstname</span></th>
<td><input name="firstname" type="text" /></td></tr>
<tr><th style="color:blue"><span class="required">Surname</span></th>
<td><input name="surname" type="text" /></td></tr>
<tr><th>Email</th><td><input name="email" type="text" /></td></tr>
<tr><th>Position</th><td><input name="position" type="text" /></td></tr>
<tr><td align="center" colspan="2">
<input name="submit" id="submit" type="submit" value="Submit" />
</td></tr>
</table>
</form>

# Simple employee edit form
$f = HTML::Formulate->new({
   fields => [ qw(emp_id firstname surname email position) ],
   required => [ qw(firstname surname) ],
   field_attr => {
     emp_id => { type => 'hidden' },
   },
});
print $f->render(\%data);

outputs the same form but with an additional 'hidden' emp_id input field, and data values from the %data hash in the relevant input field values.

DESCRIPTION

HTML::Formulate is a module used to produce HTML forms. It uses a presentation definition hash to control the output format, which is great for flexible programmatic control, inheritance, and subclassing (e.g. defining site- or section-specific HTML::Formulate subclasses and then producing standardised forms very easily). On the other hand, it doesn't give you the very fine-grained control over presentation that you get using a template-based system.

HTML::Formulate handles only form presentation - it doesn't include any validation or processing functionality (although it does include functionality for displaying validation errors). If you're after the processing end of things, check out CGI::FormFactory, which uses HTML::Formulate and Data::FormValidator to manage the full HTML form lifecycle. CGI::FormBuilder is another good alternative.

HTML::Formulate also allows form definitions to be built in multiple stages, so that you can define a base form with common definitions (either on the fly or as a dedicated subclass) and then provide only the details that are particular to your new form.

FORM DEFINITION ARGUMENTS

HTML::Formulate is a subclass of HTML::Tabulate, and uses HTML tables to lay out its forms. It supports all the standard HTML::Tabulate presentation definition arguments - see HTML::Tabulate for details. Probably the following are the most important:

fields

Arrayref of field names

field_attr

Hashref defining per-field attributes (important - see HTML::Tabulate for the details, and the FIELD ATTRIBUTE ARGUMENTS section below)

table, tr, th, td

Hashrefs defining attributes to be applied to the relevant table element

title, text, caption

Scalars or subroutine references (see HTML::Tabulate) defining simple text elements to be displayed before or after the form

In addition, HTML::Formulate supports the following form-specific definition arguments:

form

Hashref defining attributes to be set on the form tag. Can also be used as a scalar with a false value to omit the form elements from the rendered form (presumably because you're handling them explicitly yourself). Default: form => { method => 'post' }

formtype

Scalar - currently just 'form' or 'table'. A 'table' form suppresses all the HTML::Formulate extras, producing a vanilla HTML::Tabulate table from your definition.

submit

Arrayref of submit/button/reset elements to display at the bottom of your form. By default, these are rendered as (e.g. for submit => [ 'Search' ]):

type="submit" name="search" id="search" value="Search"

input elements. To change attributes, use a named field_attr section (see FIELD ATTRIBUTE ARGUMENTS below) or the special field_attr '-submit' section (which applies to all submit elements). Default:

submit => [ 'submit' ]

To omit submit elements altogether, use:

submit => []            # or submit => 0

required

Arrayref of field names that are required/mandatory fields, or a scalar field name if only one field is required. The special field names 'ALL' and 'NONE' are also supported. Default: none.

Required fields are marked as such, usually on the field label. By default, required field labels are rendered as:

<th style="color:blue"><span class="required">Label</span></th>

This colours required labels blue, by default, but can be overridden by defining a CSS 'required' class. This default itself can be overridden by defining per-field attributes (typically 'th' and 'label_format') for the '-required' pseudo-field (see '-required' below).

hidden

Arrayref of field names to render as hidden elements, or a hashref of field => value pairs. Hiddens can also be defined within a field attribute section by setting the field type to 'hidden'. Default: none.

use_name_as_id

Boolean. If true, HTML::Formulate will add an id attribute set to the field name on any input/select/textarea fields that do not have an id.

errors

Hashref defining a set of field => error_message pairs to be displayed as errors on the form (multiple error messages per field are also supported by making the value an arrayref of error messages).

Errors are displayed in two ways: the list error messages are error messages is displayed either above the form or in a third column within the form (see 'errors_where' to control which); and error field labels are modified to indicate an error.

Error messages are listed in form field order if the error key is recognised as a field name ('field errors'); any others are not recognised as field names ('extra errors') are listed after this. Error messages are treated as sprintf messages, with a '%s' in the message replaced by the field label (for field errors) or the error key (for extra errors). Errors without %s placeholders therefore just get rendered as literals.

Field error labels are by default rendered in a similar way to 'required' fields, like this:

<th style="color:red"><span class="error_field">Label</span></th>

This colours error labels red, but can be overridden by defining a CSS 'error_field' class. This default itself can be overridden by defining per-field attributes (typically 'th' and 'label_format') for the '-errors' pseudo-field (see '-errors' below).

Error messages, if defined, are displayed as a list before the form (errors_where => 'top') or in a third table column annotating each field (errors_where => 'column'). See 'errors_where' following.

errors_where

Scalar, either 'top' or 'column'. If 'top', error messages are displayed as a list before the form - see errors_format to control how this list is formatted. If 'column', error messages are displayed in a third table column immediately to the right of the relevant field. Default: top.

errors_format

Subroutine reference or scalar defining how to format 'top' style error messages. If a subroutine, is passed the array of messages as arguments, and is expected to return a string containing the formatted errors. If a scalar, is interpreted as a sprintf pattern to be applied per-message, with the results simply joined with newlines - in particular, the scalar should include any HTML line breaks required. e.g.

errors_format => '<span class="error">%s</span><br />'

Default is a subref that renders messages like this:

<p style="color:red;font-weight:bold">
<span class="error">Error 1</span>
<span class="error">Error 2</span>
</p>

producing red bold error messages, which can be overridden by defining a CSS 'error' class.

submit_location

Scalar, either 'bottom' or 'top' or 'both'. Location of submit elements. Default: bottom.

FIELD ATTRIBUTE ARGUMENTS

Per-field attributes can be defined in a 'field_attr' hashref (see HTML::Tabulate for the details). In addition to the standard HTML::Tabulate attributes (and the '-defaults' pseudo-field), HTML::Formulate defines some extra attributes and a set of extra pseudo-fields, as follows.

FORMULATE PSEUDO-FIELDS

-select

A hashref of field attributes to be used for all <select> fields, The order in which attributes are defined is global -defaults, then -select attributes, and then per-field attributes, allowing defaults to be overridden as required.

-submit

A hashref of field attributes to be used for all submit fields, as defined in the top-level 'submit' argument. The order in which attributes are defined is global -defaults, then -submit attributes, and then per-field attributes, allowing defaults to be overridden as required.

-required

A hashref of field attributes to be used for all required fields, as defined in the top-level 'required' argument. The order in which attributes are defined is global -defaults, then -required attributes, and then per-field attributes, allowing defaults to be overridden as required.

For example, to turn off the default 'required' field styling, you could define -required as follows:

-required => {
  th => {},
  label_format => '',
}

-errors

A hashref of field attributes to be used for any field defined as having a validation error in the top-level 'errors' argument. The order in which attributes are defined is global -defaults, then -required attributes (if applicable), then -errors attributes, and then per-field attributes.

FORMULATE FIELD ATTRIBUTES

type

An enum defining what sort of control to present for this field, usually being an HTML input type (or equivalent). Current valid values are:

text textarea password radio select checkbox hidden file image button
display static omit

Of these display, static, and omit do not have obvious HTML correlates - these mean:

display

The field is a readonly display field, and any value simply displayed as text i.e. no input fields are produced e.g.

emp_name => { type => 'display' }

is rendered as the following line:

<tr><th>Emp Name</th><td>Fred Flintstone</td></tr>

static

The field is a readonly display field, but is passed when the field is submitted i.e. both a text label and a hidden input field are produced e.g.

emp_name => { type => 'static' }

is rendered as the following line:

<tr><th>Emp Name</th>
<td>Fred Flintstone
<input name="emp_name" type="hidden" value="Fred Flintstone" />
</td></tr>

(some formatting newlines added). If you want to use a different label than the underlying data value, you can set a scalar or coderef 'vlabel', similar to selects. A scalar vlabel is interpreted as a sprintf pattern passed the current data value i.e. $label = sprintf($vlabel,$value). For example:

emp_id => { type => 'static', value => '123', vlabel => 'E%05d' }

is rendered as:

<tr><th>Emp ID</th>
<td>E00123<input name="emp_id" type="hidden" value="123" />
</td></tr>

(newlines added).

A coderef vlabel is passed the standard arguments: value, row, field e.g.

emp_id => { type => 'static', value => '123', vlabel => sub {
  my ($value, $row, $field) = @_;
  sprintf 'E%05d', $value;
}}

renders the same as the previous example.

omit

The field is to be omitted altogether i.e. no row or input field is to be included for this field. This is useful either to temporarily comment out a field without deleting its field attribute definition, or if you're doing something like building the field manually yourself for some reason, and still want it validated etc. as part of 'fields'.

required

A boolean allowing you to specify whether this field is required, as an alternative to including it in a 'required' arrayref at the top-level.

values

An arrayref or subroutine defining (or returning) a list of possible values for a field, typically used in defining the possible values of a list field e.g. a select, checkbox set, etc.

If a subroutine, it is called as follows:

$values_sub->( $field, $row );

where $field is the field name, and $row is the current data row. It is expected to return a arrayref of values to use.

vlabels

An arrayref or subroutine defining (or returning) a list of labels to be associated with the corresponding items in the values arrayref above. Alternatively, it may be (or return) a hashref defining value => label correspondences explicitly.

If a subroutine, it is called as follows:

$vlabels_sub->( $v, $field, $row )

where $v is the current value, $field is the field name, and $row is the current data row. The subroutine may return any of the following: an arrayref defining the entire list of labels for this field, in the same order as the values arrayref; a hashref defining the entire set of labels for this field, mapping values to labels; or a scalar, defining the label for the given value only.

OTHER ATTRIBUTES

All other attributes defined for a field are taken to be attributes to be applied either to the field input or textarea or select tag (if it looks like a valid attribute for the tag in question e.g. class, name, id, size, maxlength, etc.), or else are applied to the enclosing <th> and <td> table tags (as for HTML::Tabulate - see Tabulate documentation).

EXAMPLES

User login form

$f = HTML::Formulate->new({
  fields => [ qw(username password) ],
  required => 'ALL',
  submit => [ qw(login) ],
  field_attr => {
    password => { type => 'password' },
  },
});

User registration form

$f = HTML::Formulate->new({
  fields => [ qw(firstname surname email password password_confirm) ],
  required => 'ALL',
  submit => [ qw(register) ],
  field_attr => {
    qr/^password/ => { type => 'password' },
  },
});

SEE ALSO

HTML::Tabulate, CGI::FormFactory, CGI::FormBuilder

AUTHOR

Gavin Carr, <gavin@openfusion.com.au>

COPYRIGHT

Copyright 2003-2016, Gavin Carr.

This program is free software. You may copy or redistribute it under the same terms as perl itself.

cpanm HTML::Formulate

perl -MCPAN -e shell
install HTML::Formulate