CGI::FormBuilder::Template(3pm)

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

SUBCLASSING TEMPLATE ADAPTERS

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

REVISION

177       $Id: Template.pm 100 2007-03-02 18:13:13Z nwiger $
178

AUTHOR

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)