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.

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:

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' }

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

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.

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.

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.

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.

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.

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.

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.

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:

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.

(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:

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

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.

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