1CGI::FormBuilder::TemplUasteer(3C)ontributed Perl DocumeCnGtIa:t:iFoonrmBuilder::Template(3)
2
6 CGI::FormBuilder::Template - Template adapters for FormBuilder
7
9 # Define a template engine
10 package CGI::FormBuilder::Template::Whatever;
12 use base 'Whatever::Template::Module';
13 sub new {
15 my $self = shift;
16 my $class = ref($self) ⎪⎪ $self;
17 my %opt = @_;
18 # override some options
20 $opt{some_setting} = 0;
21 $opt{another_var} = 'Some Value';
22 # instantiate the template engine
24 $opt{engine} = Whatever::Template::Module->new(%opt);
25 return bless \%opt, $class;
27 }
28 sub render {
30 my $self = shift;
31 my $form = shift; # only arg is form object
32 # grab any manually-set template params
34 my %tmplvar = $form->tmpl_param;
35 # example template manipulation
37 my $html = $self->{engine}->do_template(%tmplvar);
38 return $html; # scalar HTML is returned
40 }
41
43 This documentation describes the usage of FormBuilder templates, as
44 well as how to write your own template adapter.
45 The template engines serve as adapters between CPAN template modules
47 and FormBuilder. A template engine is invoked by using the "template"
48 option to the top-level "new()" method:
49 my $form = CGI::FormBuilder->new(
51 template => 'filename.tmpl'
52 );
53 This example points to a filename that contains an "HTML::Template"
55 compatible template to use to layout the HTML. You can also specify the
56 "template" option as a reference to a hash, allowing you to further
57 customize the template processing options, or use other template
58 engines.
59 For example, you could turn on caching in "HTML::Template" with some‐
61 thing like the following:
62 my $form = CGI::FormBuilder->new(
64 fields => \@fields,
65 template => {
66 filename => 'form.tmpl',
67 shared_cache => 1
68 }
69 );
70 As mentioned, specifying a hashref allows you to use an alternate tem‐
72 plate processing system like the "Template Toolkit". A minimal config‐
73 uration would look like this:
74 my $form = CGI::FormBuilder->new(
76 fields => \@fields,
77 template => {
78 type => 'TT2', # use Template Toolkit
79 template => 'form.tmpl',
80 },
81 );
82 The "type" option specifies the name of the engine. Currently accepted
84 types are:
85 Builtin - Included, default rendering if no template specified
87 Div - Render form using <div> (no tables)
88 HTML - HTML::Template
89 Text - Text::Template
90 TT2 - Template Toolkit
91 Fast - CGI::FastTemplate
92 In addition to one of these types, you can also specify a complete
94 package name, in which case that module will be autoloaded and its
95 "new()" and "render()" routines used. For example:
96 my $form = CGI::FormBuilder->new(
98 fields => \@fields,
99 template => {
100 type => 'My::Template::Module',
101 template => 'form.tmpl',
102 },
103 );
104 All other options besides "type" are passed to the constructor for that
106 templating system verbatim, so you'll need to consult those docs to see
107 what all the different options do. Skip down to "SEE ALSO".
108
110 In addition to the above included template engines, it is also possible
111 to write your own rendering module. If you come up with something cool,
112 please let the mailing list know!
113 To do so, you need to write a module which has a sub called "render()".
115 This sub will be called by FormBuilder when "$form->render" is called.
116 This sub can do basically whatever it wants, the only thing it has to
117 do is return a scalar string which is the HTML to print out.
118 This is actually not hard. Here's a simple adapter which would manipu‐
120 late an "HTML::Template" style template:
121 # This file is My/HTML/Template.pm
123 package My::HTML::Template;
124 use CGI::FormBuilder::Template::HTML;
126 use base 'CGI::FormBuilder::Template::HTML';
127 sub render {
129 my $self = shift; # class object
130 my $form = shift; # $form as only argument
131 # the template object (engine) lives here
133 my $tmpl = $self->engine;
134 # setup vars for our fields (objects)
136 for ($form->field) {
137 $tmpl->param($_ => $_->value);
138 }
139 # render output
141 my $html = $tmpl->output;
142 # return scalar;
144 return $html;
145 }
146 1; # close module
147 Then in FormBuilder:
149 use CGI::FormBuilder;
151 use My::HTML::Template; # your module
152 my $tmpl = My::HTML::Template->new;
154 my $form = CGI::FormBuilder->new(
156 fields => [qw(name email)],
157 header => 1,
158 template => $tmpl # pass template object
159 );
160 # set our company from an extra CGI param
162 my $co = $form->cgi_param('company');
163 $tmpl->engine->param(company => $co);
164 # and render like normal
166 print $form->render;
167 That's it! For more details, the best thing to do is look through the
169 guts of one of the existing template engines and go from there.
170
172 CGI::FormBuilder, CGI::FormBuilder::Template::HTML, CGI::Form‐
173 Builder::Template::Text, CGI::FormBuilder::Template::TT2, CGI::Form‐
174 Builder::Template::Fast
175
177 $Id: Template.pm 100 2007-03-02 18:13:13Z nwiger $
178
180 Copyright (c) 2000-2006 Nate Wiger <nate@wiger.org>. All Rights
181 Reserved.
182 This module is free software; you may copy this under the terms of the
184 GNU General Public License, or the Artistic License, copies of which
185 should have accompanied your Perl kit.
186perl v5.8.8 2007-03-02 CGI::FormBuilder::Template(3)