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