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

EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT

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.

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).

In a similar way to 'required' fields, error field labels are by default rendered as:

  <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.

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.
-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 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) vlabel, similar to selects. The 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).

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 defining 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.

vlabels

An arrayref corresponding to the values arrayref above, defining a list of labels to be associated with the corresponding value. Alternatively, may be a hashref defining value => label correspondences explicitly.

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' },
      },
    });

AUTHOR

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

COPYRIGHT

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

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