1CGI::FormBuilder::TemplUasteer(3C)ontributed Perl DocumeCnGtIa:t:iFoonrmBuilder::Template(3)
2
3
4
6 CGI::FormBuilder::Template - Template adapters for FormBuilder
7
9 # Define a template engine
10
11 package CGI::FormBuilder::Template::Whatever;
12 use base 'Whatever::Template::Module';
13
14 sub new {
15 my $self = shift;
16 my $class = ref($self) || $self;
17 my %opt = @_;
18
19 # override some options
20 $opt{some_setting} = 0;
21 $opt{another_var} = 'Some Value';
22
23 # instantiate the template engine
24 $opt{engine} = Whatever::Template::Module->new(%opt);
25
26 return bless \%opt, $class;
27 }
28
29 sub render {
30 my $self = shift;
31 my $form = shift; # only arg is form object
32
33 # grab any manually-set template params
34 my %tmplvar = $form->tmpl_param;
35
36 # example template manipulation
37 my $html = $self->{engine}->do_template(%tmplvar);
38
39 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
46 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
50 my $form = CGI::FormBuilder->new(
51 template => 'filename.tmpl'
52 );
53
54 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
60 For example, you could turn on caching in "HTML::Template" with
61 something like the following:
62
63 my $form = CGI::FormBuilder->new(
64 fields => \@fields,
65 template => {
66 filename => 'form.tmpl',
67 shared_cache => 1
68 }
69 );
70
71 As mentioned, specifying a hashref allows you to use an alternate
72 template processing system like the "Template Toolkit". A minimal
73 configuration would look like this:
74
75 my $form = CGI::FormBuilder->new(
76 fields => \@fields,
77 template => {
78 type => 'TT2', # use Template Toolkit
79 template => 'form.tmpl',
80 },
81 );
82
83 The "type" option specifies the name of the engine. Currently accepted
84 types are:
85
86 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
93 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
97 my $form = CGI::FormBuilder->new(
98 fields => \@fields,
99 template => {
100 type => 'My::Template::Module',
101 template => 'form.tmpl',
102 },
103 );
104
105 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
114 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
119 This is actually not hard. Here's a simple adapter which would
120 manipulate an "HTML::Template" style template:
121
122 # This file is My/HTML/Template.pm
123 package My::HTML::Template;
124
125 use CGI::FormBuilder::Template::HTML;
126 use base 'CGI::FormBuilder::Template::HTML';
127
128 sub render {
129 my $self = shift; # class object
130 my $form = shift; # $form as only argument
131
132 # the template object (engine) lives here
133 my $tmpl = $self->engine;
134
135 # setup vars for our fields (objects)
136 for ($form->field) {
137 $tmpl->param($_ => $_->value);
138 }
139
140 # render output
141 my $html = $tmpl->output;
142
143 # return scalar;
144 return $html;
145 }
146 1; # close module
147
148 Then in FormBuilder:
149
150 use CGI::FormBuilder;
151 use My::HTML::Template; # your module
152
153 my $tmpl = My::HTML::Template->new;
154
155 my $form = CGI::FormBuilder->new(
156 fields => [qw(name email)],
157 header => 1,
158 template => $tmpl # pass template object
159 );
160
161 # set our company from an extra CGI param
162 my $co = $form->cgi_param('company');
163 $tmpl->engine->param(company => $co);
164
165 # and render like normal
166 print $form->render;
167
168 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,
173 CGI::FormBuilder::Template::Text, CGI::FormBuilder::Template::TT2,
174 CGI::FormBuilder::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
183 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.
186
187
188
189perl v5.12.0 2007-03-02 CGI::FormBuilder::Template(3)