.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "CGI::FormBuilder::Template::TT2 3"
.TH CGI::FormBuilder::Template::TT2 3 2025-12-13 "perl v5.42.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
CGI::FormBuilder::Template::TT2 \- FormBuilder interface to Template Toolkit
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 8
\&    my $form = CGI::FormBuilder\->new(
\&                    fields   => \e@fields,
\&                    template => {
\&                        type => \*(AqTT2\*(Aq,
\&                        template => \*(Aqform.tmpl\*(Aq,
\&                        variable => \*(Aqform\*(Aq,
\&                    }
\&               );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This engine adapts \fBFormBuilder\fR to use \f(CW\*(C`Template Toolkit\*(C'\fR.  To do so, 
specify the \f(CW\*(C`template\*(C'\fR option as a hashref which includes the \f(CW\*(C`type\*(C'\fR
option set to \f(CW\*(C`TT2\*(C'\fR and the \f(CW\*(C`template\*(C'\fR option set to the name of the
template you want processed. You can also add \f(CW\*(C`variable\*(C'\fR as an option
(among others) to denote the variable name that you want the form data
to be referenced by:
.PP
.Vb 8
\&    my $form = CGI::FormBuilder\->new(
\&                    fields => \e@fields,
\&                    template => {
\&                        type => \*(AqTT2\*(Aq,
\&                        template => \*(Aquserinfo.tmpl\*(Aq,
\&                        variable => \*(Aqform\*(Aq,
\&                    }
\&               );
.Ve
.PP
The following methods are provided (usually only used internally):
.SS engine
.IX Subsection "engine"
Returns a reference to the \f(CW\*(C`Template\*(C'\fR object
.SS prepare
.IX Subsection "prepare"
Returns a hash of all the fields ready to be rendered.
.SS render
.IX Subsection "render"
Uses the prepared hash and expands the template, returning a string of HTML.
.SH TEMPLATES
.IX Header "TEMPLATES"
The template might look something like this:
.PP
.Vb 10
\&    <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>
.Ve
.PP
By default, the Template Toolkit makes all the form and field
information accessible through simple variables.
.PP
.Vb 8
\&    [% 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)
.Ve
.PP
You can specify the \f(CW\*(C`variable\*(C'\fR option to have all these variables
accessible under a certain namespace.  For example:
.PP
.Vb 8
\&    my $form = CGI::FormBuilder\->new(
\&        fields => \e@fields,
\&        template => {
\&             type => \*(AqTT2\*(Aq,
\&             template => \*(Aqform.tmpl\*(Aq,
\&             variable => \*(Aqform\*(Aq
\&        },
\&    );
.Ve
.PP
With \f(CW\*(C`variable\*(C'\fR set to \f(CW\*(C`form\*(C'\fR the variables are accessible as:
.PP
.Vb 3
\&    [% form.jshead %]
\&    [% form.start  %]
\&    etc.
.Ve
.PP
You can access individual fields via the \f(CW\*(C`field\*(C'\fR variable.
.PP
.Vb 5
\&    For a field named...  The field data is in...
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    job                   [% form.field.job   %]
\&    size                  [% form.field.size  %]
\&    email                 [% form.field.email %]
.Ve
.PP
Each field contains various elements.  For example:
.PP
.Vb 1
\&    [% 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
.Ve
.PP
The \f(CW\*(C`fields\*(C'\fR 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:
.PP
.Vb 5
\&    [% FOREACH field = form.fields %]
\&    <tr>
\&     <td>[% field.label %]</td> <td>[% field.field %]</td>
\&    </tr>
\&    [% END %]
.Ve
.PP
If you want to customise any of the Template Toolkit options, you can
set the \f(CW\*(C`engine\*(C'\fR option to contain a reference to an existing
\&\f(CW\*(C`Template\*(C'\fR object or hash reference of options which are passed to
the \f(CW\*(C`Template\*(C'\fR constructor.  You can also set the \f(CW\*(C`data\*(C'\fR item to
define any additional variables you want accessible when the template
is processed.
.PP
.Vb 10
\&    my $form = CGI::FormBuilder\->new(
\&        fields => \e@fields,
\&        template => {
\&             type => \*(AqTT2\*(Aq,
\&             template => \*(Aqform.tmpl\*(Aq,
\&             variable => \*(Aqform\*(Aq,
\&             engine   => {
\&                  INCLUDE_PATH => \*(Aq/usr/local/tt2/templates\*(Aq,
\&             },
\&             data => {
\&                  version => 1.23,
\&                  author  => \*(AqFred Smith\*(Aq,
\&             },
\&        },
\&    );
.Ve
.PP
For further details on using the Template Toolkit, see \f(CW\*(C`Template\*(C'\fR or
<http://www.template\-toolkit.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CGI::FormBuilder, CGI::FormBuilder::Template, Template
.SH REVISION
.IX Header "REVISION"
\&\f(CW$Id:\fR TT2.pm 100 2007\-03\-02 18:13:13Z nwiger $
.SH AUTHOR
.IX Header "AUTHOR"
Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
.PP
Template Tookit support is largely due to a huge patch from Andy Wardley.
.PP
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.