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