1CGI::FormBuilder::TemplUasteer(3C)ontributed Perl DocumeCnGtIa:t:iFoonrmBuilder::Template(3)
2
3
4

NAME

6       CGI::FormBuilder::Template - Template adapters for FormBuilder
7

SYNOPSIS

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

DESCRIPTION

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           CGI_SSI -  CGI::SSI
93
94       In addition to one of these types, you can also specify a complete
95       package name, in which case that module will be autoloaded and its
96       "new()" and "render()" routines used. For example:
97
98           my $form = CGI::FormBuilder->new(
99                           fields => \@fields,
100                           template => {
101                               type => 'My::Template::Module',
102                               template => 'form.tmpl',
103                           },
104                      );
105
106       All other options besides "type" are passed to the constructor for that
107       templating system verbatim, so you'll need to consult those docs to see
108       what all the different options do. Skip down to "SEE ALSO".
109

SUBCLASSING TEMPLATE ADAPTERS

111       In addition to the above included template engines, it is also possible
112       to write your own rendering module. If you come up with something cool,
113       please let the mailing list know!
114
115       To do so, you need to write a module which has a sub called "render()".
116       This sub will be called by FormBuilder when "$form->render" is called.
117       This sub can do basically whatever it wants, the only thing it has to
118       do is return a scalar string which is the HTML to print out.
119
120       This is actually not hard. Here's a simple adapter which would
121       manipulate an "HTML::Template" style template:
122
123           # This file is My/HTML/Template.pm
124           package My::HTML::Template;
125
126           use CGI::FormBuilder::Template::HTML;
127           use base 'CGI::FormBuilder::Template::HTML';
128
129           sub render {
130               my $self = shift;    # class object
131               my $form = shift;    # $form as only argument
132
133               # the template object (engine) lives here
134               my $tmpl = $self->engine;
135
136               # setup vars for our fields (objects)
137               for ($form->field) {
138                   $tmpl->param($_ => $_->value);
139               }
140
141               # render output
142               my $html = $tmpl->output;
143
144               # return scalar;
145               return $html;
146           }
147           1;  # close module
148
149       Then in FormBuilder:
150
151           use CGI::FormBuilder;
152           use My::HTML::Template;   # your module
153
154           my $tmpl = My::HTML::Template->new;
155
156           my $form = CGI::FormBuilder->new(
157                           fields   => [qw(name email)],
158                           header   => 1,
159                           template => $tmpl   # pass template object
160                      );
161
162           # set our company from an extra CGI param
163           my $co = $form->cgi_param('company');
164           $tmpl->engine->param(company => $co);
165
166           # and render like normal
167           print $form->render;
168
169       That's it! For more details, the best thing to do is look through the
170       guts of one of the existing template engines and go from there.
171

SEE ALSO

173       CGI::FormBuilder, CGI::FormBuilder::Template::HTML,
174       CGI::FormBuilder::Template::Text, CGI::FormBuilder::Template::TT2,
175       CGI::FormBuilder::Template::Fast, CGI::FormBuilder::Template::CGI_SSI
176

REVISION

178       $Id: Template.pm 97 2007-02-06 17:10:39Z nwiger $
179

AUTHOR

181       Copyright (c) Nate Wiger <http://nateware.com>. All Rights 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.34.0                      2021-07-22     CGI::FormBuilder::Template(3)
Impressum