1# NAME 2 3HTML::FillInForm - Populates HTML Forms with data. 4 5# VERSION 6 7version 2.22 8 9# SYNOPSIS 10 11Fill HTML form with data. 12 13 $output = HTML::FillInForm->fill( \$html, $q ); 14 $output = HTML::FillInForm->fill( \@html, [$q1,$q2] ); 15 $output = HTML::FillInForm->fill( \*HTML, \%data ); 16 $output = HTML::FillInForm->fill( 't.html', [\%data1,%data2] ); 17 18The HTML can be provided as a scalarref, arrayref, filehandle or file. The data can come from one or more 19hashrefs, or objects which support a param() method, like CGI.pm, [Apache::Request](https://metacpan.org/pod/Apache%3A%3ARequest), etc. 20 21# DESCRIPTION 22 23This module fills in an HTML form with data from a Perl data structure, allowing you 24to keep the HTML and Perl separate. 25 26Here are two common use cases: 27 281\. A user submits an HTML form without filling out a required field. You want 29to redisplay the form with all the previous data in it, to make it easy for the 30user to see and correct the error. 31 322\. You have just retrieved a record from a database and need to display it in 33an HTML form. 34 35# fill 36 37The basic syntax is seen above the Synopsis. There are a few additional options. 38 39## Options 40 41### target => 'form1' 42 43Suppose you have multiple forms in a html file and only want to fill in one. 44 45 $output = HTML::FillInForm->fill(\$html, $q, target => 'form1'); 46 47This will fill in only the form inside 48 49 <FORM name="form1"> ... </FORM> 50 51### fill\_password => 0 52 53Passwords are filled in by default. To disable: 54 55 fill_password => 0 56 57### ignore\_fields => \[\] 58 59To disable the filling of some fields: 60 61 ignore_fields => ['prev','next'] 62 63### disable\_fields => \[\] 64 65To disable fields from being edited: 66 67 disable_fields => [ 'uid', 'gid' ] 68 69### invalid\_fields => \[\] 70 71To mark fields as being invalid (CSS class set to "invalid" or 72whatever you set invalid\_class to): 73 74 invalid_fields => [ 'uid', 'gid' ] 75 76### invalid\_class => "invalid" 77 78The CSS class which will be used to mark fields invalid. Defaults to 79"invalid". 80 81### clear\_absent\_checkboxes => 0 82 83Absent fields are not cleared or in any way changed. This is 84not what you want when you deal with checkboxes which are not sent 85by browser at all when cleared by user. 86 87To remove "checked" attribute from checkboxes and radio buttons and 88attribute "selected" from options of select lists for which there's no 89data: 90 91 clear_absent_checkboxes => 1 92 93## File Upload fields 94 95File upload fields cannot be supported directly. Workarounds include asking the 96user to re-attach any file uploads or fancy server-side storage and 97referencing. You are on your own. 98 99## Clearing Fields 100 101Fields are cleared if you set their value to an empty string or empty arrayref but not undef: 102 103 # this will leave the form element foo untouched 104 HTML::FillInForm->fill(\$html, { foo => undef }); 105 106 # this will set clear the form element foo 107 HTML::FillInForm->fill(\$html, { foo => "" }); 108 109It has been suggested to add a option to change the behavior so that undef 110values will clear the form elements. Patches welcome. 111 112You can also use `clear_absent_checkboxes` option to clear 113checkboxes, radio buttons and selects without corresponding keys in 114the data: 115 116 # this will set clear the form element foo (and all others except 117 # bar) 118 HTML::FillInForm->fill(\$html, { bar => 123 }, 119 clear_absent_checkboxes => 1); 120 121# Old syntax 122 123You probably need to read no further. The remaining docs concern the 1241.x era syntax, which is still supported. 125 126## new 127 128Call `new()` to create a new FillInForm object: 129 130 $fif = HTML::FillInForm->new; 131 $fif->fill(...); 132 133In theory, there is a slight performance benefit to calling `new()` before `fill()` if you make multiple 134calls to `fill()` before you destroy the object. Benchmark before optimizing. 135 136## fill ( old syntax ) 137 138Instead of having your HTML and data types auto-detected, you can declare them explicitly in your 139call to `fill()`: 140 141HTML source options: 142 143 arrayref => @html 144 scalarref => $html 145 file => \*HTML 146 file => 't.html' 147 148Fill Data options: 149 150 fobject => $data_obj # with param() method 151 fdat => \%data 152 153Additional methods are also available: 154 155 fill_file(\*HTML,...); 156 fill_file('t.html',...); 157 fill_arrayref(\@html,...); 158 fill_scalarref(\$html,...); 159 160# USING AN ALTERNATE PARSER 161 162It's possible to use an alternate parser to [HTML::Parser](https://metacpan.org/pod/HTML%3A%3AParser) if the alternate 163provides a sufficiently compatible interface. For example, when a Pure Perl 164implementation of HTML::Parser appears, it could be used for portability. The syntax 165is simply to provide a `parser_class` to new(); 166 167 HTML::FillInForm->new( parser_class => 'MyAlternate::Parser' ); 168 169# CALLING FROM OTHER MODULES 170 171## Apache::PageKit 172 173To use HTML::FillInForm in [Apache::PageKit](https://metacpan.org/pod/Apache%3A%3APageKit) is easy. It is 174automatically called for any page that includes a <form> tag. 175It can be turned on or off by using the `fill_in_form` configuration 176option. 177 178## Apache::ASP v2.09 and above 179 180HTML::FillInForm is now integrated with Apache::ASP. To activate, use 181 182 PerlSetVar FormFill 1 183 $Response->{FormFill} = 1 184 185## HTML::Mason 186 187Using HTML::FillInForm from HTML::Mason is covered in the FAQ on 188the masonhq.com website at 189[http://www.masonhq.com/?FAQ:HTTPAndHTML#h-how\_can\_i\_populate\_form\_values\_automatically\_](http://www.masonhq.com/?FAQ:HTTPAndHTML#h-how_can_i_populate_form_values_automatically_) 190 191# SECURITY 192 193Note that you might want to think about caching issues if you have password 194fields on your page. There is a discussion of this issue at 195 196http://www.perlmonks.org/index.pl?node\_id=70482 197 198In summary, some browsers will cache the output of CGI scripts, and you 199can control this by setting the Expires header. For example, use 200`-expires` in [CGI.pm](https://metacpan.org/pod/CGI.pm) or set `browser_cache` to _no_ in 201Config.xml file of [Apache::PageKit](https://metacpan.org/pod/Apache%3A%3APageKit). 202 203# TRANSLATION 204 205Kato Atsushi has translated these docs into Japanese, available from 206 207http://perldoc.jp 208 209# BUGS 210 211Please submit any bug reports to tjmather@maxmind.com. 212 213# NOTES 214 215Requires Perl 5.005 and [HTML::Parser](https://metacpan.org/pod/HTML%3A%3AParser) version 3.26. 216 217I wrote this module because I wanted to be able to insert CGI data 218into HTML forms, 219but without combining the HTML and Perl code. CGI.pm and Embperl allow you so 220insert CGI data into forms, but require that you mix HTML with Perl. 221 222There is a nice review of the module available here: 223[http://www.perlmonks.org/index.pl?node\_id=274534](http://www.perlmonks.org/index.pl?node_id=274534) 224 225# SEE ALSO 226 227[HTML::Parser](https://metacpan.org/pod/HTML%3A%3AParser), 228[Data::FormValidator](https://metacpan.org/pod/Data%3A%3AFormValidato), 229[HTML::Template](https://metacpan.org/pod/HTML%3A%3ATemplate), 230[Apache::PageKit](https://metacpan.org/pod/Apache%3A%3APageKit) 231 232# CREDITS 233 234Fixes, Bug Reports, Docs have been generously provided by: 235 236 Alex Kapranoff Miika Pekkarinen 237 Michael Fisher Sam Tregar 238 Tatsuhiko Miyagawa Joseph Yanni 239 Boris Zentner Philip Mak 240 Dave Rolsky Jost Krieger 241 Patrick Michael Kane Gabriel Burka 242 Ade Olonoh Bill Moseley 243 Tom Lancaster James Tolley 244 Martin H Sluka Dan Kubb 245 Mark Stosberg Alexander Hartmaier 246 Jonathan Swartz Paul Miller 247 Trevor Schellhorn Anthony Ettinger 248 Jim Miner Simon P. Ditner 249 Paul Lindner Michael Peters 250 Maurice Aubrey Trevor Schellhorn 251 Andrew Creer 252 253Thanks! 254 255# AUTHOR 256 257TJ Mather, tjmather@maxmind.com 258 259# COPYRIGHT AND LICENSE 260 261This software is copyright (c) 2000 by TJ Mather, tjmather@maxmind.com. 262 263This is free software; you can redistribute it and/or modify it under 264the same terms as the Perl 5 programming language system itself. 265