---
name: "CGI::FormBuilder::Template::TT2"
section: "3pm"
platform: "linux"
package: "perl-cgi-formbuilder"
version: "3.20-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/CGI::FormBuilder::Template::TT2"
---

# CGI::FormBuilder::Template::TT2(3pm)

FormBuilder interface to Template Toolkit

## NAME

CGI::FormBuilder::Template::TT2 - FormBuilder interface to Template Toolkit

## SYNOPSIS

```
    my $form = CGI::FormBuilder->new(
                    fields   => \@fields,
                    template => {
                        type => 'TT2',
                        template => 'form.tmpl',
                        variable => 'form',
                    }
               );
```

## DESCRIPTION

This engine adapts **FormBuilder** to use `"Template Toolkit"`.  To do so,  specify the `"template"` option as a hashref which includes the `"type"` option set to `"TT2"` and the `"template"` option set to the name of the template you want processed. You can also add `"variable"` as an option (among others) to denote the variable name that you want the form data to be referenced by:

```
    my $form = CGI::FormBuilder->new(
                    fields => \@fields,
                    template => {
                        type => 'TT2',
                        template => 'userinfo.tmpl',
                        variable => 'form',
                    }
               );
```

The following methods are provided (usually only used internally):

### engine

Returns a reference to the `"Template"` object

### prepare

Returns a hash of all the fields ready to be rendered.

### render

Uses the prepared hash and expands the template, returning a string of HTML.

## TEMPLATES

The template might look something like this:

```
    <html>
    <head>
      <title>[% form.title %]</title>
      [% form.jshead %]
    </head>
    <body>
      [% form.start %]
      <table>
        [% FOREACH field = form.fields %]
        <tr valign="top">
          <td>
            [% field.required
                  ? "<b>$field.label</b>"
                  : field.label
            %]
          </td>
          <td>
            [% IF field.invalid %]
            Missing or invalid entry, please try again.
        <br/>
        [% END %]
        [% field.field %]
      </td>
    </tr>
        [% END %]
        <tr>
          <td colspan="2" align="center">
            [% form.submit %] [% form.reset %]
          </td>
        </tr>
      </table>
      [% form.end %]
    </body>
    </html>
```

By default, the Template Toolkit makes all the form and field information accessible through simple variables.

```
    [% jshead %]  -  JavaScript to stick in <head>
    [% title  %]  -  The <title> of the HTML form
    [% start  %]  -  Opening <form> tag and internal fields
    [% submit %]  -  The submit button(s)
    [% reset  %]  -  The reset button
    [% end    %]  -  Closing </form> tag
    [% fields %]  -  List of fields
    [% field  %]  -  Hash of fields (for lookup by name)
```

You can specify the `"variable"` option to have all these variables accessible under a certain namespace.  For example:

```
    my $form = CGI::FormBuilder->new(
        fields => \@fields,
        template => {
             type => 'TT2',
             template => 'form.tmpl',
             variable => 'form'
        },
    );
```

With `"variable"` set to `"form"` the variables are accessible as:

```
    [% form.jshead %]
    [% form.start  %]
    etc.
```

You can access individual fields via the `"field"` variable.

```
    For a field named...  The field data is in...
    --------------------  -----------------------
    job                   [% form.field.job   %]
    size                  [% form.field.size  %]
    email                 [% form.field.email %]
```

Each field contains various elements.  For example:

```
    [% myfield = form.field.email %]
    [% myfield.label    %]  # text label
    [% myfield.field    %]  # field input tag
    [% myfield.value    %]  # first value
    [% myfield.values   %]  # list of all values
    [% myfield.option   %]  # first value
    [% myfield.options  %]  # list of all values
    [% myfield.required %]  # required flag
    [% myfield.invalid  %]  # invalid flag
```

The `"fields"` variable contains a list of all the fields in the form. To iterate through all the fields in order, you could do something like this:

```
    [% FOREACH field = form.fields %]
    <tr>
     <td>[% field.label %]</td> <td>[% field.field %]</td>
    </tr>
    [% END %]
```

If you want to customise any of the Template Toolkit options, you can set the `"engine"` option to contain a reference to an existing `"Template"` object or hash reference of options which are passed to the `"Template"` constructor.  You can also set the `"data"` item to define any additional variables you want accessible when the template is processed.

```
    my $form = CGI::FormBuilder->new(
        fields => \@fields,
        template => {
             type => 'TT2',
             template => 'form.tmpl',
             variable => 'form',
             engine   => {
                  INCLUDE_PATH => '/usr/local/tt2/templates',
             },
             data => {
                  version => 1.23,
                  author  => 'Fred Smith',
             },
        },
    );
```

For further details on using the Template Toolkit, see `"Template"` or \<http://www.template-toolkit.org\>

## SEE ALSO

CGI::FormBuilder, CGI::FormBuilder::Template, Template

## REVISION

`$Id:` TT2.pm 100 2007-03-02 18:13:13Z nwiger $

## AUTHOR

Copyright (c) Nate Wiger \<http://nateware.com\>. All Rights Reserved.

Template Tookit support is largely due to a huge patch from Andy Wardley.

This module is free software; you may copy this under the terms of the GNU General Public License, or the Artistic License, copies of which should have accompanied your Perl kit.