2
###########################################################################
3
# Copyright (c) Nate Wiger http://nateware.com. All Rights Reserved.
4
# Please visit http://formbuilder.org for tutorials, support, and examples.
5
###########################################################################
7
package CGI::FormBuilder::Template::CGI_SSI;
11
CGI::FormBuilder::Template::CGI_SSI - FormBuilder interface to CGI::SSI
15
my $form = CGI::FormBuilder->new(
19
file => "template.html",
28
no warnings 'uninitialized';
30
use CGI::FormBuilder::Util;
34
our $REVISION = do { (my $r='$Revision: 97 $') =~ s/\D+//g; $r };
35
our $VERSION = '3.06';
38
# For legacy reasons, and due to its somewhat odd interface,
39
# CGI::SSI vars use a completely different naming scheme.
42
'js-head' => 'jshead',
43
'form-title' => 'title',
44
'form-start' => 'start',
45
'form-submit' => 'submit',
46
'form-reset' => 'reset',
48
'form-invalid' => 'invalid',
49
'form-required' => 'required',
52
our %FIELD_VARS = map { $_ => "$_-%s" } qw(
68
my $class = ref($self) || $self;
69
my $opt = arghash(@_);
71
$opt->{die_on_bad_params} = 0; # force to avoid blow-ups
74
delete $opt2{virtual};
77
$opt->{engine} = CGI::SSI->new(%opt2);
79
return bless $opt, $class; # rebless
83
return shift()->{engine};
88
my $tvar = shift || puke "Missing template expansion hashref (\$form->prepare failed?)";
90
while(my($to, $from) = each %FORM_VARS) {
91
debug 1, "renaming attr $from to: <!--#echo var=\"$to\">";
92
$tvar->{$to} = "$tvar->{$from}";
96
# For CGI::SSI, each data struct is manually assigned
97
# to a separate <!--#echo var=... -->"
100
for my $field (@{$tvar->{fields}}) {
102
# Field name is usually a good idea
103
my $name = $field->{name};
104
debug 1, "expanding field: $name";
107
my @value = @{$tvar->{field}{$name}{values} || []};
108
my @options = @{$tvar->{field}{$name}{options} || []};
111
# Auto-expand all of our field tags, such as field, label, value
112
# comment, error, etc, etc
115
while(my($key, $str) = each %FIELD_VARS) {
116
my $var = sprintf $str, $name;
117
$all_loop{$key} = $tvar->{field}{$name}{$key};
118
$tvar->{$var} = "$tvar->{field}{$name}{$key}"; # fuck Perl
119
debug 2, "<!--#echo var=\"$var\"> = " . $all_loop{$str};
122
# kill our previous fields list
123
$tvar->{fields} = \@fieldlist;
125
# loop thru each field we have and set the tmpl_param
126
while(my($param, $tag) = each %$tvar) {
127
$self->{engine}->set($param => $tag);
132
if($self->{virtual}) {
133
return $self->engine->include(virtual=>$self->{virtual});
136
return $self->engine->include(file=>$self->{file});
138
if($self->{string}) {
139
return $self->engine->process($self->{string});
149
This engine adapts B<FormBuilder> to use C<CGI::SSI>.
151
You can specify any options which C<< CGI::SSI->new >>
152
accepts by using a hashref:
154
my $form = CGI::FormBuilder->new(
158
file => 'form.shtml',
163
In addition to CGI::SSI B<new> arguments, you can also
164
specify C<file>, C<virtual>, or C<string> argument.
166
The following methods are provided (usually only used internally):
170
Returns a reference to the C<CGI::SSI> object
174
Returns a hash of all the fields ready to be rendered.
178
Uses the prepared hash and expands the template, returning a string of HTML.
182
In your template, each of the form fields will correspond directly to
183
a C<< <!--#echo --> >> of the same name prefixed with "field-" in the
184
template. So, if you defined a field called "email", then you would
185
setup a variable called C<< <!--#echo var="field-email" --> >> in your template.
187
In addition, there are a couple special fields:
189
<!--#echo var="js-head" --> - JavaScript to stick in <head>
190
<!--#echo var="form-title" --> - The <title> of the HTML form
191
<!--#echo var="form-start" --> - Opening <form> tag and internal fields
192
<!--#echo var="form-submit" --> - The submit button(s)
193
<!--#echo var="form-reset" --> - The reset button
194
<!--#echo var="form-end" --> - Just the closing </form> tag
196
Let's look at an example C<form.html> template we could use:
200
<title>User Information</title>
201
<!--#echo var="js-head" --><!-- this holds the JavaScript code -->
203
<!--#echo var="form-start" --><!-- this holds the initial form tag -->
204
<h3>User Information</h3>
205
Please fill out the following information:
206
<!-- each of these <!--#echo -->'s corresponds to a field -->
207
<p>Your full name: <!--#echo var="field-name" -->
208
<p>Your email address: <!--#echo var="field-email" -->
209
<p>Choose a password: <!--#echo var="field-password" -->
210
<p>Please confirm it: <!--#echo var="field-confirm_password-->
211
<p>Your home zipcode: <!--#echo var="field-zipcode -->
213
<!--#echo var="form-submit" --><!-- this holds the form submit button -->
214
</form><!-- can also use "tmpl_var form-end", same thing -->
216
As you see, you get a C<< <!--#echo --> >> for each for field you define.
218
However, you may want even more control. That is, maybe you want
219
to specify every nitty-gritty detail of your input fields, and
220
just want this module to take care of the statefulness of the
221
values. This is no problem, since this module also provides
222
several other C<< <tmpl_var> >> tags as well:
224
<!--#echo var="value-[field] --> - The value of a given field
225
<!--#echo var="label-[field] --> - The human-readable label
226
<!--#echo var="comment-[field] --> - Any optional comment
227
<!--#echo var="error-[field] --> - Error text if validation fails
228
<!--#echo var="required-[field] --> - See if the field is required
230
This means you could say something like this in your template:
232
<!--#echo var="label-email" -->:
233
<input type="text" name="email" value="<!--#echo var="value-email" -->">
234
<font size="-1"><i><!--#echo var="error-email" --></i></font>
236
And B<FormBuilder> would take care of the value stickiness for you,
237
while you have control over the specifics of the C<< <input> >> tag.
238
A sample expansion may create HTML like the following:
241
<input type="text" name="email" value="nate@wiger.org">
242
<font size="-1"><i>You must enter a valid value</i></font>
244
Note, though, that this will only get the I<first> value in the case
245
of a multi-value parameter (for example, a multi-select list).
246
Multiple values (loops) in C<< CGI_SSI >> are not yet implemented.
248
For more information on templates, see L<HTML::Template>.
252
L<CGI::FormBuilder>, L<CGI::FormBuilder::Template>, L<HTML::Template>
256
$Id: HTML.pm 97 2007-02-06 17:10:39Z nwiger $
260
Copyright (c) L<Nate Wiger|http://nateware.com>. All Rights Reserved.
262
This module is free software; you may copy this under the terms of
263
the GNU General Public License, or the Artistic License, copies of
264
which should have accompanied your Perl kit.