HTML::SuperForm(3pm)

1HTML::SuperForm(3)    User Contributed Perl Documentation   HTML::SuperForm(3)
2
3
4

NAME

6       HTML::SuperForm - HTML form generator
7

SYNOPSIS

9           use HTML::SuperForm;
10           use Apache::Constants qw(OK);
11
12           sub handler {
13               my $r = shift;
14
15               my $form = HTML::SuperForm->new($r);
16
17               my $text = $form->text(name => 'text',
18                                      default => 'Default Text');
19
20               my $textarea = $form->textarea(name => 'textarea',
21                                              default => 'More Default Text');
22
23               my $select = $form->select(name => 'select',
24                                          default => 2,
25                                          values => [ 0, 1, 2, 3],
26                                          labels => {
27                                              0 => 'Zero',
28                                              1 => 'One',
29                                              2 => 'Two',
30                                              3 => 'Three'
31                                          });
32
33               my $output = <<"END_HTML";
34           <html>
35           <body>
36               <form>
37               Text Field: $text<br>
38               Text Area: $textarea<br>
39               Select: $select
40               </form>
41           </body>
42           </html>
43           END_HTML
44
45
46               $r->content_type('text/html');
47               $r->send_http_header;
48
49               $r->print($output);
50               return OK;
51           }
52
53           OR
54
55           #!/usr/bin/perl
56
57           my $form = HTML::SuperForm->new();
58
59           my $text = $form->text(name => 'text',
60                                  default => 'Default Text');
61
62           my $textarea = $form->textarea(name => 'textarea',
63                                          default => 'More Default Text');
64
65           my $select = $form->select(name => 'select',
66                                      default => 2,
67                                      values => [ 0, 1, 2, 3],
68                                      labels => {
69                                          0 => 'Zero',
70                                          1 => 'One',
71                                          2 => 'Two',
72                                          3 => 'Three'
73                                      });
74
75           my $output = <<"END_HTML";
76           <html>
77           <body>
78               <form>
79               Text Field: $text<br>
80               Text Area: $textarea<br>
81               Select: $select
82               </form>
83           </body>
84           </html>
85           END_HTML
86
87           print "Content-Type: text/html\n\n";
88           print $output;
89

DESCRIPTION

91       Used in its basic form, this module provides an interface for
92       generating basic HTML form elements much like HTML::StickyForms does.
93       The main difference is HTML::SuperForm returns HTML::SuperForm::Field
94       objects rather than plain HTML. This allows for more flexibilty when
95       generating forms for a complex application.
96
97       To get the most out of this module, use it as a base (Super) class for
98       your own form object which generates your own custom fields. If you
99       don't use it this way, I guess there's really nothing Super about it.
100       Example are shown later in the document.
101
102       The interface was designed with mod_perl and the Template Toolkit in
103       mind, but it works equally well in any cgi environment.
104

METHODS

106   CONSTRUCTOR
107       new($r, $field_object), new($r), new()
108           Creates a new HTML::SuperForm object.
109
110           If $arg is an Apache object then an Apache::Request object will be
111           created from it to retrieve the parameters. If you don't have
112           Apache::Request installed then it behaves as if $arg is undef.
113
114           If $arg is an Apache::Request object, CGI object or a hash
115           reference, then it is used to retrieve the parameters. If no
116           argument is given or the argument isn't an instance or subclass of
117           the objects mentioned above then the parameters are retreived
118           through the environment variables. If called in a non-cgi
119           environment, no stickyness is applied.
120
121           It is recommended to use CGI or Apache::Request because the
122           parameter parsing included in HTML::SuperForm doesn't include the
123           complexities that CGI and Apache::Request take in to account and
124           only works with application/x-www-form-urlencoded forms.
125
126           If you pass $field_object, then HTML::SuperForm will use that
127           object instead of HTML::SuperForm::Field. See *field_object()*
128           below and HTML::SuperForm::Field for more on this.
129
130   ACCESSORS AND MUTATORS
131       These methods get and set values contained in the form object.
132
133       set_sticky($flag), sticky($flag)
134       set_sticky(),      sticky()
135           Returns the state of the sticky flag. If an argument is given the
136           sticky flag is set to that value. The sticky flag defaults to
137           false. The flag determines whether the form uses the default values
138           (false) or submitted values (true).
139
140       fallback($flag), fallback()
141           Sets whether the form's fields "fall back" to their default values
142           if the form is sticky and no data has been submitted for those
143           fields.  Defaults to false.
144
145       values_as_labels($flag), values_as_labels()
146           Returns the state of the values_as_labels flag. If an argument is
147           given flag is set to that value. The values_as_labels flag defaults
148           to true. The flag determines whether select fields, checkboxes and
149           radio buttons use their values as labels if no labels are given.
150
151       well_formed($flag), well_formed()
152           Returns the state of the well_formed flag. If an argument is given
153           flag is set to that value. The well_formed flag defaults to true.
154           The flag determines whether the HTML generated is also well-formed
155           XML.
156
157       start_form(%args), start_form(\%args)
158           Returns the starting HTML form tag with all the attributes you pass
159           it. These are some arguments you might give (each is also a method
160           that returns its value):
161
162           name()
163               The name of the form.
164
165           method()
166               The method in which the form is submitted (GET or POST).  The
167               default is POST.
168
169               If the method set in start_form() equals the method that is
170               detected from the current request then the form is set to
171               sticky.
172
173           action()
174               The url to which the form is submitted.
175
176           Any other attribute you specify can be accessed by calling its
177           method (i.e. if you pass in ( target => 'newWindow', onSubmit =>
178           'CheckForm()' ), $form->target will return 'newWindow', and
179           $form->onSubmit will return 'CheckForm()'). The names are case
180           sensitive so be consistent.
181
182       no_of_fields($name)
183           Returns the number of fields which have the given name.
184
185       param(%args), param(\%args), param($name)
186           Gets the parameters with name $name or sets parameters with names
187           equal to the keys of %args and values equal to the values of %args.
188           The parameters are used by the form object as if they were
189           submitted values.
190
191       exists_param($name)
192           Returns true if a value exists for the parameter named $name.
193           Otherwise, returns false.
194
195       params()
196           Returns a reference to a hash of the submitted parameters.
197
198   GET AND SET
199       Since I intended HTML::SuperForm's main use to be as a base class, I
200       made these methods so subclasses can store information within the
201       object without worrying about overriding important keys in the object.
202
203       set(%args), set(\%args)
204           Stores infomation in form for later retrieval by get().
205
206       get(@keys)
207           When called in list context, returns an array of values that were
208           previously stored with set(). When called in scalar context,
209           returns a reference to an array of values or, if only one key is
210           given, the corresponding single value.
211
212   INTERNAL METHODS
213       You probably won't ever need to use these methods unless you are in a
214       subclass of HTML::SuperForm or HTML::SuperForm::Field.
215
216       set_default(%args), set_default(\%args)
217           Sets default values in form for each key/value pair in %args.
218
219       add_default(%args), add_default(\%args)
220           Adds default values to form for each key/value pair in %args.
221
222       field_object()
223           Returns the field object (the string, not an actual object) that is
224           the base class of all the field objects.
225
226           This will almost always be HTML::SuperForm::Field.  If you subclass
227           HTML::SuperForm::Field (as a replacement for
228           HTML::SuperForm::Field, not as a field like Text or Select etc.)
229           then you have to tell the form object to use it.  Also, if you do
230           that, make sure you write your own field classes (Text, Select
231           etc.).  Consult documentation for HTML::SuperForm::Field for more
232           on this.
233
234   FIELD METHODS
235       These methods return objects with their string operators overloaded to
236       output HTML.
237
238       text(%args), text(\%args)
239           Returns an HTML::SuperForm::Field::Text object.
240
241       textarea(%args), textarea(\%args)
242           Returns an HTML::SuperForm::Field::Textarea object.
243
244       hidden(%args), hidden(\%args)
245           Returns an HTML::SuperForm::Field::Hidden object.
246
247       password(%args), password(\%args)
248           Returns an HTML::SuperForm::Field::Password object.
249
250       select(%args), select(\%args)
251           Returns an HTML::SuperForm::Field::Select object.
252
253       checkbox(%args), checkbox(\%args)
254           Returns an HTML::SuperForm::Field::Checkbox object.
255
256       radio(%args), radio(\%args)
257           Returns an HTML::SuperForm::Field::Radio object.
258
259       checkbox_group(%args), checkbox_group(\%args)
260           Returns an HTML::SuperForm::Field::CheckboxGroup object.
261
262       radio_group(%args), radio_group(\%args)
263           Returns an HTML::SuperForm::Field::RadioGroup object.
264
265       submit(%args), submit(\%args)
266           Returns an HTML::SuperForm::Field::Submit object.
267

EXAMPLES

269       This example shows how to make a form object that can generate a
270       counter field along with all the other basic fields. A counter field
271       consists of a text field, an increment button and a decrement button.
272       Consult the documentation for HTML::SuperForm::Field for more
273       information about field inheritance.
274
275           package myForm;
276
277           use strict;
278           use myForm::Counter;
279
280           use base 'HTML::SuperForm';
281
282           sub counter {
283               return myForm::Counter->new(@_);
284           }
285
286           sub javascript {
287               my $js = <<END_JAVASCRIPT;
288           <script language="JavaScript">
289           function Increment(field) {
290               field.value++;
291           }
292
293           function Decrement(field) {
294               field.value--;
295           }
296           </script>
297           END_JAVASCRIPT
298
299               return $js;
300           }
301
302           1;
303
304           package myForm::Counter;
305
306           use strict;
307           use base 'HTML::SuperForm::Field';
308
309           use HTML::SuperForm::Field::Text;
310
311           sub prepare {
312               my $self = shift;
313
314               my $form_name = $self->form->name;
315               my $field_name = $self->name;
316
317               my $js_name = "document.$form_name.$field_name";
318
319               my $text = HTML::SuperForm::Field::Text->new(name => $self->name, default => $self->value, size => 4);
320
321               $self->set(text => $text);
322               $self->set(inc => qq|<a style="cursor: pointer" onmouseup="Increment($js_name)"><img src="/icons/up.gif" border=0></a>|);
323               $self->set(dec => qq|<a style="cursor: pointer" onmouseup="Decrement($js_name)"><img src="/icons/down.gif" border=0></a>|);
324           }
325
326           sub inc {
327               my $self = shift;
328
329               return $self->get('inc');
330           }
331
332           sub dec {
333               my $self = shift;
334
335               return $self->get('dec');
336           }
337
338           sub text {
339               my $self = shift;
340
341               return $self->get('text');
342           }
343
344           sub arrows_right {
345               my $self = shift;
346
347               my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
348
349               my $tag = "<table>\n";
350               $tag .= qq|    <tr>\n|;
351               $tag .= qq|        <td align="center">$text</td>\n|;
352               $tag .= qq|        <td align="center">$inc<br/>$dec</td>\n|;
353               $tag .= qq|    </tr>\n|;
354               $tag .= "</table>\n";
355
356               return $tag;
357           }
358
359           sub arrows_left {
360               my $self = shift;
361
362               my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
363
364               my $tag = "<table>\n";
365               $tag .= qq|    <tr>\n|;
366               $tag .= qq|        <td align="center">$inc<br/>$dec</td>\n|;
367               $tag .= qq|        <td align="center">$text</td>\n|;
368               $tag .= qq|    </tr>\n|;
369               $tag .= "</table>\n";
370
371               return $tag;
372           }
373
374           sub default_layout {
375               my $self = shift;
376
377               my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
378
379               my $tag = "<table>\n";
380               $tag .= qq|    <tr><td align="center">$inc</td></tr>\n|;
381               $tag .= qq|    <tr><td align="center">$text</td></tr>\n|;
382               $tag .= qq|    <tr><td align="center">$dec</td></tr>\n|;
383               $tag .= "</table>\n";
384
385               return $tag;
386           }
387
388           sub to_html {
389               my $self = shift;
390
391               my $tag = $self->default_layout;
392
393               return $tag;
394           }
395
396           1;
397
398       This might seem complex but by using it this way you get the following
399       functionality:
400
401           package myHandler;
402
403           use strict;
404           use myForm;
405           use Apache::Constants qw(OK);
406           use Template;
407
408           sub handler($$) {
409               my $self = shift;
410               my $r = shift;
411
412               my $form = myForm->new($r);
413
414               my $tt = Template->new(INCLUDE_PATH => '/my/template/path');
415
416               my $output;
417
418               $tt->process('my_template.tt', { form => $form }, \$output);
419
420               $r->content_type('text/html');
421               $r->send_http_header();
422
423               $r->print($output);
424
425               return OK;
426           }
427
428           1;
429
430           my_template.tt:
431
432           <html>
433               <head>
434               <title>Flexibility with HTML::SuperForm</title>
435               [% form.javascript %]
436               </head>
437               <body>
438               [% form.start_form %]
439               Default Counter Layout: [% form.counter(name => 'counter1', default => 0) %] <br/>
440               Counter with increment/decrement buttons on the left: [% form.counter(name => 'counter2', default => 0).arrows_left %] <br/>
441               Counter with increment/decrement buttons on the right: [% form.counter(name => 'counter3', default => 0).arrows_right %] <br/>
442               Counter with multiple increment/decrement buttons wherever you want: <br/>
443               [% counter = form.counter(name => 'counter4', default => 0) %]
444               <table>
445                   <tr><td>[% counter.inc %]</td><td></td><td>[% counter.inc %]</tr>
446                   <tr><td></td><td></td>[% counter.text %]<td></tr>
447                   <tr><td>[% counter.dec %]</td><td></td><td>[% counter.dec %]</tr>
448               </table>
449               [% form.submit %]
450               [% form.end_form %]
451               </body>
452           </html>
453

AUTHOR

470       John Allwine <jallwine86@yahoo.com>
471

COPYRIGHT

473       This program is free software; you can redistribute it and/or modify it
474       under the same terms as Perl itself.
475
476       The full text of the license can be found in the LICENSE file included
477       with this module.
478
479
480
481perl v5.36.0                      2023-01-20                HTML::SuperForm(3)