.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (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 .\" ======================================================================== .\" .IX Title "CGI::FormBuilder::Template::Text 3" .TH CGI::FormBuilder::Template::Text 3 2024-12-15 "perl v5.40.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::Text \- FormBuilder interface to Text::Template .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 8 \& my $form = CGI::FormBuilder\->new( \& fields => \e@fields, \& template => { \& type => \*(AqText\*(Aq, \& template => \*(Aqform.tmpl\*(Aq, \& variable => \*(Aqform\*(Aq, \& } \& ); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This engine adapts \fBFormBuilder\fR to use \f(CW\*(C`Text::Template\*(C'\fR. Usage is very similar to Template Toolkit: .PP .Vb 7 \& my $form = CGI::FormBuilder\->new( \& fields => \e@fields, \& template => { \& type => \*(AqText\*(Aq, # use Text::Template \& template => \*(Aqform.tmpl\*(Aq, \& } \& ); .Ve .PP The default options passed into \f(CW\*(C`Text::Template\->new()\*(C'\fR with this calling form are: .PP .Vb 3 \& TYPE => \*(AqFILE\*(Aq \& SOURCE => \*(Aqform.tmpl\*(Aq \& DELIMITERS => [\*(Aq<%\*(Aq,\*(Aq%>\*(Aq] .Ve .PP As these params are passed for you, your template will look very similar to ones used by Template Toolkit and \f(CW\*(C`HTML::Mason\*(C'\fR (the Text::Template default delimiters are \f(CW\*(C`{\*(C'\fR and \f(CW\*(C`}\*(C'\fR, but using alternative delimiters speeds it up by about 25%, and the \f(CW\*(C`<%\*(C'\fR and \f(CW\*(C`%>\*(C'\fR delimiters are good, familiar-looking alternatives). .PP The following methods are provided (usually only used internally): .SS engine .IX Subsection "engine" Returns a reference to the \f(CW\*(C`Text::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" .Vb 8 \& <% $jshead %> \- JavaScript to stick in \& <% $title %> \- The 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 Note that you refer to variables with a preceding \f(CW\*(C`$\*(C'\fR, just like in Perl. Like Template Toolkit, you can specify a variable to place fields under: .PP .Vb 8 \& my $form = CGI::FormBuilder\->new( \& fields => \e@fields, \& template => { \& type => \*(AqText\*(Aq, \& template => \*(Aqform.tmpl\*(Aq, \& variable => \*(Aqform\*(Aq \& }, \& ); .Ve .PP Unlike Template Toolkit, though, these will not be placed in OO-style, dot-separated vars. Instead, a hash will be created which you then reference: .PP .Vb 3 \& <% $form{jshead} %> \& <% $form{start} %> \& etc. .Ve .PP And field data is in a hash-of-hashrefs format: .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 Since \f(CW\*(C`Text::Template\*(C'\fR looks so much like Perl, you can access individual elements and create variables like so: .PP .Vb 11 \& <% \& my $myfield = $form{field}{email}; \& $myfield\->{label}; # text label \& $myfield\->{field}; # field input tag \& $myfield\->{value}; # first value \& $myfield\->{values}; # list of all values \& $myfield\->{options}; # list of all options \& $myfield\->{required}; # required flag \& $myfield\->{invalid}; # invalid flag \& $myfield\->{error}; # error string if invalid \& %> \& \& <% \& for my $field (@{$form{fields}}) { \& $OUT .= "<tr>\en<td>" . $field\->{label} . "</td> <td>" \& . $field\->{field} . "</td>\en<tr>"; \& } \& %> .Ve .PP In addition, when using the engine option, you supply an existing Text::Template object or a hash of parameters to be passed to \f(CWnew()\fR. For example, you can ask for different delimiters yourself: .PP .Vb 10 \& my $form = CGI::FormBuilder\->new( \& fields => \e@fields, \& template => { \& type => \*(AqText\*(Aq, \& template => \*(Aqform.tmpl\*(Aq, \& variable => \*(Aqform\*(Aq, \& engine => { \& DELIMITERS => [ \*(Aq[@\-\-\*(Aq, \*(Aq\-\-@]\*(Aq ], \& }, \& data => { \& version => 1.23, \& author => \*(AqFred Smith\*(Aq, \& }, \& }, \& ); .Ve .PP If you pass a hash of parameters, you can override the \f(CW\*(C`TYPE\*(C'\fR and \f(CW\*(C`SOURCE\*(C'\fR parameters, as well as any other \f(CW\*(C`Text::Template\*(C'\fR options. For example, you can pass in a string template with \f(CW\*(C`TYPE => STRING\*(C'\fR instead of loading it from a file. You must specify \fBboth\fR \f(CW\*(C`TYPE\*(C'\fR and \f(CW\*(C`SOURCE\*(C'\fR if doing so. The good news is this is trivial: .PP .Vb 10 \& my $form = CGI::FormBuilder\->new( \& fields => \e@fields, \& template => { \& type => \*(AqText\*(Aq, \& variable => \*(Aqform\*(Aq, \& engine => { \& TYPE => \*(AqSTRING\*(Aq, \& SOURCE => $string, \& DELIMITERS => [ \*(Aq[@\-\-\*(Aq, \*(Aq\-\-@]\*(Aq ], \& }, \& data => { \& version => 1.23, \& author => \*(AqFred Smith\*(Aq, \& }, \& }, \& ); .Ve .PP If you get the crazy idea to let users of your application pick the template file (strongly discouraged) and you're getting errors, look at the \f(CW\*(C`Text::Template\*(C'\fR documentation for the \f(CW\*(C`UNTAINT\*(C'\fR feature. .PP Also, note that \f(CW\*(C`Text::Template\*(C'\fR's \f(CW\*(C`PREPEND => \*(Aquse strict;\*(Aq\*(C'\fR option is not recommended due to the dynamic nature for \f(CW\*(C`FormBuilder\*(C'\fR. If you use it, then you'll have to declare each variable that \f(CW\*(C`FormBuilder\*(C'\fR puts into your template with \&\f(CW\*(C`use vars qw($jshead\*(Aq ... etc);\*(C'\fR .PP If you're really stuck on this, though, a workaround is to say: .PP .Vb 1 \& PREPEND => \*(Aquse strict; use vars qw(%form);\*(Aq .Ve .PP and then set the option \f(CW\*(C`variable => \*(Aqform\*(Aq\*(C'\fR. That way you can have strict Perl without too much hassle, except that your code might be exhausting to look at :\-). Things like \f(CW\*(C`$form{field}{your_field_name}{field}\*(C'\fR end up being all over the place, instead of the nicer short forms. .PP Finally, when you use the \f(CW\*(C`data\*(C'\fR template option, the keys you specify will be available to the template as regular variables. In the above example, these would be \&\f(CW\*(C`<% $version %>\*(C'\fR and \f(CW\*(C`<% $author %>\*(C'\fR. And complex datatypes are easy: .PP .Vb 4 \& data => { \& anArray => [ 1, 2, 3 ], \& aHash => { orange => \*(Aqtangy\*(Aq, chocolate => \*(Aqsweet\*(Aq }, \& } .Ve .PP This becomes the following in your template: .PP .Vb 4 \& <% \& @anArray; # you can use $myArray[1] etc. \& %aHash; # you can use $myHash{chocolate} etc. \& %> .Ve .PP For more information, please consult the \f(CW\*(C`Text::Template\*(C'\fR documentation. .SH "SEE ALSO" .IX Header "SEE ALSO" CGI::FormBuilder, CGI::FormBuilder::Template, Text::Template .SH REVISION .IX Header "REVISION" \&\f(CW$Id:\fR Text.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 Text::Template support is due to huge contributions by Jonathan Buhacoff. Thanks man. .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.