1HTML-SuperForm version 1.04
2===========================
3
4INSTALLATION
5
6To install this module type the following:
7
8 perl Makefile.PL
9 make
10 make test
11 make install
12
13NAME
14 HTML::SuperForm - HTML form generator
15
16SYNOPSIS
17 use HTML::SuperForm;
18 use Apache::Constants qw(OK);
19
20 sub handler {
21 my $r = shift;
22
23 my $form = HTML::SuperForm->new($r);
24
25 my $text = $form->text(name => 'text',
26 default => 'Default Text');
27
28 my $textarea = $form->textarea(name => 'textarea',
29 default => 'More Default Text');
30
31 my $select = $form->select(name => 'select',
32 default => 2,
33 values => [ 0, 1, 2, 3],
34 labels => {
35 0 => 'Zero',
36 1 => 'One',
37 2 => 'Two',
38 3 => 'Three'
39 });
40
41 my $output = <<"END_HTML";
42 <html>
43 <body>
44 <form>
45 Text Field: $text<br>
46 Text Area: $textarea<br>
47 Select: $select
48 </form>
49 </body>
50 </html>
51 END_HTML
52
53 $r->content_type('text/html');
54 $r->send_http_header;
55
56 $r->print($output);
57 return OK;
58 }
59
60 1;
61
62 OR
63
64 #!/usr/bin/perl
65
66 my $form = HTML::SuperForm->new();
67
68 my $text = $form->text(name => 'text',
69 default => 'Default Text');
70
71 my $textarea = $form->textarea(name => 'textarea',
72 default => 'More Default Text');
73
74 my $select = $form->select(name => 'select',
75 default => 2,
76 values => [ 0, 1, 2, 3],
77 labels => {
78 0 => 'Zero',
79 1 => 'One',
80 2 => 'Two',
81 3 => 'Three'
82 });
83
84 my $output = <<"END_HTML";
85 <html>
86 <body>
87 <form>
88 Text Field: $text<br>
89 Text Area: $textarea<br>
90 Select: $select
91 </form>
92 </body>
93 </html>
94 END_HTML
95
96 print "Content-Type: text/html\n\n";
97 print $output;
98
99DESCRIPTION
100 Used in its basic form, this module provides an interface for generating
101 basic HTML form elements much like HTML::StickyForms does. The main
102 difference is HTML::SuperForm returns HTML::SuperForm::Field objects
103 rather than plain HTML. This allows for more flexibilty when generating
104 forms for a complex application.
105
106 To get the most out of this module, use it as a base (Super) class for
107 your own form object which generates your own custom fields. If you
108 don't use it this way, I guess there's really nothing Super about it.
109 Example are shown later in the document.
110
111 The interface was designed with mod_perl and the Template Toolkit in
112 mind, but it works equally well in any cgi environment.
113
114METHODS
115 CONSTRUCTOR
116 *new($arg, $field_object)*, *new($arg)*, *new()*
117 Creates a new HTML::SuperForm object.
118
119 If $arg is an Apache object then an Apache::Request object will be
120 created from it to retrieve the parameters. If you don't have
121 Apache::Request installed then it behaves as if $arg is undef.
122
123 If $arg is an Apache::Request object, CGI object or a hash
124 reference, then it is used to retrieve the parameters. If no
125 argument is given or the argument isn't an instance or subclass of
126 the objects mentioned above then the parameters are retreived
127 through the environment variables. If called in a non-cgi
128 environment, no stickyness is applied.
129
130 It is recommended to use CGI or Apache::Request because the
131 parameter parsing included in HTML::SuperForm doesn't include the
132 complexities that CGI and Apache::Request take in to account and
133 only works with application/x-www-form-urlencoded forms.
134
135 If you pass $field_object, then HTML::SuperForm will use that object
136 instead of HTML::SuperForm::Field. See *field_object()* below and
137 HTML::SuperForm::Field for more on this.
138
139 ACCESSORS AND MUTATORS
140 These methods get and set values contained in the form object.
141
142 *set_sticky($flag)*, *sticky($flag)*
143 *set_sticky()*, *sticky()*
144 Returns the state of the sticky flag. If an argument is given the
145 sticky flag is set to that value. The sticky flag defaults to false.
146 The flag determines whether the form uses the default values (false)
147 or submitted values (true).
148
149 *fallback($flag)*, *fallback()*
150 Sets whether the form's fields "fall back" to their default values
151 if the form is sticky and no data has been submitted for those
152 fields. Defaults to false.
153
154 *values_as_labels($flag)*, *values_as_labels()*
155 Returns the state of the values_as_labels flag. If an argument is
156 given flag is set to that value. The values_as_labels flag defaults
157 to true. The flag determines whether select fields, checkboxes and
158 radio buttons use their values as labels if no labels are given.
159
160 *well_formed($flag)*, *well_formed()*
161 Returns the state of the well_formed flag. If an argument is given
162 flag is set to that value. The well_formed flag defaults to true.
163 The flag determines whether the HTML generated is also well-formed
164 XML.
165
166 *start_form(%args)*, *start_form(\%args)*
167 Returns the starting HTML form tag with all the attributes you pass
168 it. These are some arguments you might give (each is also a method
169 that returns its value):
170
171 *name()*
172 The name of the form.
173
174 *method()*
175 The method in which the form is submitted (GET or POST). The
176 default is POST.
177
178 If the method set in *start_form()* equals the method that is
179 detected from the current request then the form is set to
180 sticky.
181
182 *action()*
183 The url to which the form is submitted.
184
185 Any other attribute you specify can be accessed by calling its
186 method (i.e. if you pass in ( target => 'newWindow', onSubmit =>
187 'CheckForm()' ), $form->target will return 'newWindow', and
188 $form->onSubmit will return 'CheckForm()'). The names are case
189 sensitive so be consistent.
190
191 *no_of_fields($name)*
192 Returns the number of fields which have the given name.
193
194 *param(%args)*, *param(\%args)*, *param($name)*
195 Gets the parameters with name $name or sets parameters with names
196 equal to the keys of %args and values equal to the values of %args.
197 The parameters are used by the form object as if they were submitted
198 values.
199
200 *exists_param($name)*
201 Returns true if a value exists for the parameter named $name.
202 Otherwise, returns false.
203
204 *params()*
205 Returns a reference to a hash of the submitted parameters.
206
207 GET AND SET
208 Since I intended HTML::SuperForm's main use to be as a base class, I
209 made these methods so subclasses can store information within the object
210 without worrying about overriding important keys in the object.
211
212 *set(%args)*, *set(\%args)*
213 Stores infomation in form for later retrieval by get().
214
215 *get(@keys)*
216 When called in list context, returns an array of values that were
217 previously stored with set(). When called in scalar context, returns
218 a reference to an array of values or, if only one key is given, the
219 corresponding single value.
220
221 INTERNAL METHODS
222 You probably won't ever need to use these methods unless you are in a
223 subclass of HTML::SuperForm or HTML::SuperForm::Field.
224
225 *set_default(%args)*, *set_default(\%args)*
226 Sets default values in form for each key/value pair in %args.
227
228 *add_default(%args)*, *add_default(\%args)*
229 Adds default values to form for each key/value pair in %args.
230
231 *field_object()*
232 Returns the field object (the string, not an actual object) that is
233 the base class of all the field objects.
234
235 This will almost always be HTML::SuperForm::Field. If you subclass
236 HTML::SuperForm::Field (as a replacement for HTML::SuperForm::Field,
237 not as a field like Text or Select etc.) then you have to tell the
238 form object to use it. Also, if you do that, make sure you write
239 your own field classes (Text, Select etc.). Consult documentation
240 for HTML::SuperForm::Field for more on this.
241
242 FIELD METHODS
243 These methods return objects with their string operators overloaded to
244 output HTML.
245
246 *text(%args)*, *text(\%args)*
247 Returns an HTML::SuperForm::Field::Text object.
248
249 *textarea(%args)*, *textarea(\%args)*
250 Returns an HTML::SuperForm::Field::Textarea object.
251
252 *hidden(%args)*, *hidden(\%args)*
253 Returns an HTML::SuperForm::Field::Hidden object.
254
255 *password(%args)*, *password(\%args)*
256 Returns an HTML::SuperForm::Field::Password object.
257
258 *select(%args)*, *select(\%args)*
259 Returns an HTML::SuperForm::Field::Select object.
260
261 *checkbox(%args)*, *checkbox(\%args)*
262 Returns an HTML::SuperForm::Field::Checkbox object.
263
264 *radio(%args)*, *radio(\%args)*
265 Returns an HTML::SuperForm::Field::Radio object.
266
267 *checkbox_group(%args)*, *checkbox_group(\%args)*
268 Returns an HTML::SuperForm::Field::CheckboxGroup object.
269
270 *radio_group(%args)*, *radio_group(\%args)*
271 Returns an HTML::SuperForm::Field::RadioGroup object.
272
273 *submit(%args)*, *submit(\%args)*
274 Returns an HTML::SuperForm::Field::Submit object.
275
276EXAMPLES
277 This example shows how to make a form object that can generate a counter
278 field along with all the other basic fields. A counter field consists of
279 a text field, an increment button and a decrement button. Consult the
280 documentation for HTML::SuperForm::Field for more information about
281 field inheritance.
282
283 package myForm;
284
285 use strict;
286 use myForm::Counter;
287
288 use base 'HTML::SuperForm';
289
290 sub counter {
291 return myForm::Counter->new(@_);
292 }
293
294 sub javascript {
295 my $js = <<END_JAVASCRIPT;
296 <script language="JavaScript">
297 function Increment(field) {
298 field.value++;
299 }
300
301 function Decrement(field) {
302 field.value--;
303 }
304 </script>
305 END_JAVASCRIPT
306
307 return $js;
308 }
309
310 1;
311
312 package myForm::Counter;
313
314 use strict;
315 use base 'HTML::SuperForm::Field';
316
317 use HTML::SuperForm::Field::Text;
318
319 sub prepare {
320 my $self = shift;
321
322 my $form_name = $self->form->name;
323 my $field_name = $self->name;
324
325 my $js_name = "document.$form_name.$field_name";
326
327 my $text = HTML::SuperForm::Field::Text->new(name => $self->name, default => $self->value, size => 4);
328
329 $self->set(text => $text);
330 $self->set(inc => qq|<a style="cursor: pointer" onmouseup="Increment($js_name)"><img src="/icons/up.gif" border=0></a>|);
331 $self->set(dec => qq|<a style="cursor: pointer" onmouseup="Decrement($js_name)"><img src="/icons/down.gif" border=0></a>|);
332 }
333
334 sub inc {
335 my $self = shift;
336
337 return $self->get('inc');
338 }
339
340 sub dec {
341 my $self = shift;
342
343 return $self->get('dec');
344 }
345
346 sub text {
347 my $self = shift;
348
349 return $self->get('text');
350 }
351
352 sub arrows_right {
353 my $self = shift;
354
355 my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
356
357 my $tag = "<table>\n";
358 $tag .= qq| <tr>\n|;
359 $tag .= qq| <td align="center">$text</td>\n|;
360 $tag .= qq| <td align="center">$inc<br/>$dec</td>\n|;
361 $tag .= qq| </tr>\n|;
362 $tag .= "</table>\n";
363
364 return $tag;
365 }
366
367 sub arrows_left {
368 my $self = shift;
369
370 my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
371
372 my $tag = "<table>\n";
373 $tag .= qq| <tr>\n|;
374 $tag .= qq| <td align="center">$inc<br/>$dec</td>\n|;
375 $tag .= qq| <td align="center">$text</td>\n|;
376 $tag .= qq| </tr>\n|;
377 $tag .= "</table>\n";
378
379 return $tag;
380 }
381
382 sub default_layout {
383 my $self = shift;
384
385 my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
386
387 my $tag = "<table>\n";
388 $tag .= qq| <tr><td align="center">$inc</td></tr>\n|;
389 $tag .= qq| <tr><td align="center">$text</td></tr>\n|;
390 $tag .= qq| <tr><td align="center">$dec</td></tr>\n|;
391 $tag .= "</table>\n";
392
393 return $tag;
394 }
395
396 sub to_html {
397 my $self = shift;
398
399 my $tag = $self->default_layout;
400
401 return $tag;
402 }
403
404 1;
405
406 This might seem complex but by using it this way you get the following
407 functionality:
408
409 package myHandler;
410
411 use strict;
412 use myForm;
413 use Apache::Constants qw(OK);
414 use Template;
415
416 sub handler($$) {
417 my $self = shift;
418 my $r = shift;
419
420 my $form = myForm->new($r);
421
422 my $tt = Template->new(INCLUDE_PATH => '/my/template/path');
423
424 my $output;
425
426 $tt->process('my_template.tt', { form => $form }, \$output);
427
428 $r->content_type('text/html');
429 $r->send_http_header();
430
431 $r->print($output);
432
433 return OK;
434 }
435
436 1;
437
438 my_template.tt:
439
440 <html>
441 <head>
442 <title>Flexibility with HTML::SuperForm</title>
443 [% form.javascript %]
444 </head>
445 <body>
446 [% form.start_form %]
447 Default Counter Layout: [% form.counter(name => 'counter1', default => 0) %] <br/>
448 Counter with increment/decrement buttons on the left: [% form.counter(name => 'counter2', default => 0).arrows_left %] <br/>
449 Counter with increment/decrement buttons on the right: [% form.counter(name => 'counter3', default => 0).arrows_right %] <br/>
450 Counter with multiple increment/decrement buttons wherever you want: <br/>
451 [% counter = form.counter(name => 'counter4', default => 0) %]
452 <table>
453 <tr><td>[% counter.inc %]</td><td></td><td>[% counter.inc %]</tr>
454 <tr><td></td><td></td>[% counter.text %]<td></tr>
455 <tr><td>[% counter.dec %]</td><td></td><td>[% counter.dec %]</tr>
456 </table>
457 [% form.submit %]
458 [% form.end_form %]
459 </body>
460 </html>
461
462SEE ALSO
463 HTML::SuperForm::Field,
464 HTML::SuperForm::Field::Text,
465 HTML::SuperForm::Field::Textarea,
466 HTML::SuperForm::Field::Select,
467 HTML::SuperForm::Field::Checkbox,
468 HTML::SuperForm::Field::Radio,
469 HTML::SuperForm::Field::CheckboxGroup,
470 HTML::SuperForm::Field::RadioGroup
471
472TODO
473 Document its usage for fully. Give more examples.
474
475AUTHOR
476 John Allwine <jallwine86@yahoo.com>
477
478
