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) ``` Note that you refer to variables with a preceding `"$"`, just like in Perl. Like Template Toolkit, you can specify a variable to place fields under: ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', template => 'form.tmpl', variable => 'form' }, ); ``` 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: ``` <% $form{jshead} %> <% $form{start} %> etc. ``` And field data is in a hash-of-hashrefs format: ``` For a field named... The field data is in... -------------------- ----------------------- job <% $form{field}{job} %] size <% $form{field}{size} %] email <% $form{field}{email} %] ``` Since `"Text::Template"` looks so much like Perl, you can access individual elements and create variables like so: ``` <% 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>\n<td>" . $field->{label} . "</td> <td>" . $field->{field} . "</td>\n<tr>"; } %> ``` In addition, when using the engine option, you supply an existing Text::Template object or a hash of parameters to be passed to `new()`. For example, you can ask for different delimiters yourself: ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', template => 'form.tmpl', variable => 'form', engine => { DELIMITERS => [ '[@--', '--@]' ], }, data => { version => 1.23, author => 'Fred Smith', }, }, ); ``` If you pass a hash of parameters, you can override the `"TYPE"` and `"SOURCE"` parameters, as well as any other `"Text::Template"` options. For example, you can pass in a string template with `"TYPE => STRING"` instead of loading it from a file. You must specify **both** `"TYPE"` and `"SOURCE"` if doing so. The good news is this is trivial: ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', variable => 'form', engine => { TYPE => 'STRING', SOURCE => $string, DELIMITERS => [ '[@--', '--@]' ], }, data => { version => 1.23, author => 'Fred Smith', }, }, ); ``` 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 `"Text::Template"` documentation for the `"UNTAINT"` feature. Also, note that `"Text::Template"`'s `"PREPEND => 'use strict;'"` option is not recommended due to the dynamic nature for `"FormBuilder"`. If you use it, then you'll have to declare each variable that `"FormBuilder"` puts into your template with `"use vars qw($jshead' ... etc);"` If you're really stuck on this, though, a workaround is to say: ``` PREPEND => 'use strict; use vars qw(%form);' ``` and then set the option `"variable => 'form'"`. That way you can have strict Perl without too much hassle, except that your code might be exhausting to look at :-). Things like `"$form{field}{your_field_name}{field}"` end up being all over the place, instead of the nicer short forms. Finally, when you use the `"data"` template option, the keys you specify will be available to the template as regular variables. In the above example, these would be `"<% $version %>"` and `"<% $author %>"`. And complex datatypes are easy: ``` data => { anArray => [ 1, 2, 3 ], aHash => { orange => 'tangy', chocolate => 'sweet' }, } ``` This becomes the following in your template: ``` <% @anArray; # you can use $myArray[1] etc. %aHash; # you can use $myHash{chocolate} etc. %> ``` For more information, please consult the `"Text::Template"` documentation. ## SEE ALSO CGI::FormBuilder, CGI::FormBuilder::Template, Text::Template ## REVISION `$Id:` Text.pm 100 2007-03-02 18:13:13Z nwiger $ ## AUTHOR Copyright (c) Nate Wiger \<http://nateware.com\>. All Rights Reserved. Text::Template support is due to huge contributions by Jonathan Buhacoff. Thanks man. 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.

--- name: "CGI::FormBuilder::Template::Text" 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::Text" --- # CGI::FormBuilder::Template::Text(3pm) FormBuilder interface to Text::Template ## NAME CGI::FormBuilder::Template::Text - FormBuilder interface to Text::Template ## SYNOPSIS ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', template => 'form.tmpl', variable => 'form', } ); ``` ## DESCRIPTION This engine adapts **FormBuilder** to use `"Text::Template"`. Usage is very similar to Template Toolkit: ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', # use Text::Template template => 'form.tmpl', } ); ``` The default options passed into `"Text::Template->new()"` with this calling form are: ``` TYPE => 'FILE' SOURCE => 'form.tmpl' DELIMITERS => ['<%','%>'] ``` As these params are passed for you, your template will look very similar to ones used by Template Toolkit and `"HTML::Mason"` (the Text::Template default delimiters are `"{"` and `"}"`, but using alternative delimiters speeds it up by about 25%, and the `"<%"` and `"%>"` delimiters are good, familiar-looking alternatives). The following methods are provided (usually only used internally): ### engine Returns a reference to the `"Text::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 ``` <% $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) ``` Note that you refer to variables with a preceding `"$"`, just like in Perl. Like Template Toolkit, you can specify a variable to place fields under: ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', template => 'form.tmpl', variable => 'form' }, ); ``` 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: ``` <% $form{jshead} %> <% $form{start} %> etc. ``` And field data is in a hash-of-hashrefs format: ``` For a field named... The field data is in... -------------------- ----------------------- job <% $form{field}{job} %] size <% $form{field}{size} %] email <% $form{field}{email} %] ``` Since `"Text::Template"` looks so much like Perl, you can access individual elements and create variables like so: ``` <% 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>\n<td>" . $field->{label} . "</td> <td>" . $field->{field} . "</td>\n<tr>"; } %> ``` In addition, when using the engine option, you supply an existing Text::Template object or a hash of parameters to be passed to `new()`. For example, you can ask for different delimiters yourself: ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', template => 'form.tmpl', variable => 'form', engine => { DELIMITERS => [ '[@--', '--@]' ], }, data => { version => 1.23, author => 'Fred Smith', }, }, ); ``` If you pass a hash of parameters, you can override the `"TYPE"` and `"SOURCE"` parameters, as well as any other `"Text::Template"` options. For example, you can pass in a string template with `"TYPE => STRING"` instead of loading it from a file. You must specify **both** `"TYPE"` and `"SOURCE"` if doing so. The good news is this is trivial: ``` my $form = CGI::FormBuilder->new( fields => \@fields, template => { type => 'Text', variable => 'form', engine => { TYPE => 'STRING', SOURCE => $string, DELIMITERS => [ '[@--', '--@]' ], }, data => { version => 1.23, author => 'Fred Smith', }, }, ); ``` 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 `"Text::Template"` documentation for the `"UNTAINT"` feature. Also, note that `"Text::Template"`'s `"PREPEND => 'use strict;'"` option is not recommended due to the dynamic nature for `"FormBuilder"`. If you use it, then you'll have to declare each variable that `"FormBuilder"` puts into your template with `"use vars qw($jshead' ... etc);"` If you're really stuck on this, though, a workaround is to say: ``` PREPEND => 'use strict; use vars qw(%form);' ``` and then set the option `"variable => 'form'"`. That way you can have strict Perl without too much hassle, except that your code might be exhausting to look at :-). Things like `"$form{field}{your_field_name}{field}"` end up being all over the place, instead of the nicer short forms. Finally, when you use the `"data"` template option, the keys you specify will be available to the template as regular variables. In the above example, these would be `"<% $version %>"` and `"<% $author %>"`. And complex datatypes are easy: ``` data => { anArray => [ 1, 2, 3 ], aHash => { orange => 'tangy', chocolate => 'sweet' }, } ``` This becomes the following in your template: ``` <% @anArray; # you can use $myArray[1] etc. %aHash; # you can use $myHash{chocolate} etc. %> ``` For more information, please consult the `"Text::Template"` documentation. ## SEE ALSO CGI::FormBuilder, CGI::FormBuilder::Template, Text::Template ## REVISION `$Id:` Text.pm 100 2007-03-02 18:13:13Z nwiger $ ## AUTHOR Copyright (c) Nate Wiger \<http://nateware.com\>. All Rights Reserved. Text::Template support is due to huge contributions by Jonathan Buhacoff. Thanks man. 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.