1HTML::FillInForm(3) User Contributed Perl Documentation HTML::FillInForm(3)
2
6 HTML::FillInForm - Populates HTML Forms with data.
7
9 This module fills in an HTML form with data from a Perl data structure,
10 allowing you to keep the HTML and Perl separate.
11 Here are two common use cases:
13 1. A user submits an HTML form without filling out a required field.
15 You want to redisplay the form with all the previous data in it, to
16 make it easy for the user to see and correct the error.
17 2. You have just retrieved a record from a database and need to display
19 it in an HTML form.
20
22 Fill HTML form with data.
23 $output = HTML::FillInForm->fill( \$html, $q );
25 $output = HTML::FillInForm->fill( \@html, [$q1,$q2] );
26 $output = HTML::FillInForm->fill( \*HTML, \%data );
27 $output = HTML::FillInForm->fill( 't.html', [\%data1,%data2] );
28 The HTML can be provided as a scalarref, arrayref, filehandle or file.
30 The data can come from one or more hashrefs, or objects which support a
31 param() method, like CGI.pm, Apache::Request, etc.
32
34 The basic syntax is seen above the Synopsis. There are a few additional
35 options.
36 Options
38 target => 'form1'
39 Suppose you have multiple forms in a html file and only want to fill in
41 one.
42 $output = HTML::FillInForm->fill(\$html, $q, target => 'form1');
44 This will fill in only the form inside
46 <FORM name="form1"> ... </FORM>
48 fill_password => 0
50 Passwords are filled in by default. To disable:
52 fill_password => 0
54 ignore_fields => []
56 To disable the filling of some fields:
58 ignore_fields => ['prev','next']
60 disable_fields => []
62 To disable fields from being edited:
64 disable_fields => [ 'uid', 'gid' ]
66 invalid_fields => []
68 To mark fields as being invalid (CSS class set to "invalid" or whatever
70 you set invalid_class to):
71 invalid_fields => [ 'uid', 'gid' ]
73 invalid_class => "invalid"
75 The CSS class which will be used to mark fields invalid. Defaults to
77 "invalid".
78 clear_absent_checkboxes => 0
80 Absent fields are not cleared or in any way changed. This is not what
82 you want when you deal with checkboxes which are not sent by browser at
83 all when cleared by user.
84 To remove "checked" attribute from checkboxes and radio buttons and
86 attribute "selected" from options of select lists for which there's no
87 data:
88 clear_absent_checkboxes => 1
90 File Upload fields
92 File upload fields cannot be supported directly. Workarounds include
93 asking the user to re-attach any file uploads or fancy server-side
94 storage and referencing. You are on your own.
95 Clearing Fields
97 Fields are cleared if you set their value to an empty string or empty
98 arrayref but not undef:
99 # this will leave the form element foo untouched
101 HTML::FillInForm->fill(\$html, { foo => undef });
102 # this will set clear the form element foo
104 HTML::FillInForm->fill(\$html, { foo => "" });
105 It has been suggested to add a option to change the behavior so that
107 undef values will clear the form elements. Patches welcome.
108 You can also use "clear_absent_checkboxes" option to clear checkboxes,
110 radio buttons and selects without corresponding keys in the data:
111 # this will set clear the form element foo (and all others except
113 # bar)
114 HTML::FillInForm->fill(\$html, { bar => 123 },
115 clear_absent_checkboxes => 1);
116
118 You probably need to read no further. The remaining docs concern the
119 1.x era syntax, which is still supported.
120 new
122 Call "new()" to create a new FillInForm object:
123 $fif = HTML::FillInForm->new;
125 $fif->fill(...);
126 In theory, there is a slight performance benefit to calling "new()"
128 before "fill()" if you make multiple calls to "fill()" before you
129 destroy the object. Benchmark before optimizing.
130 fill ( old syntax )
132 Instead of having your HTML and data types auto-detected, you can
133 declare them explicitly in your call to "fill()":
134 HTML source options:
136 arrayref => @html
138 scalarref => $html
139 file => \*HTML
140 file => 't.html'
141 Fill Data options:
143 fobject => $data_obj # with param() method
145 fdat => \%data
146 Additional methods are also available:
148 fill_file(\*HTML,...);
150 fill_file('t.html',...);
151 fill_arrayref(\@html,...);
152 fill_scalarref(\$html,...);
153
155 It's possible to use an alternate parser to HTML::Parser if the
156 alternate provides a sufficiently compatible interface. For example,
157 when a Pure Perl implementation of HTML::Parser appears, it could be
158 used for portability. The syntax is simply to provide a "parser_class"
159 to new();
160 HTML::FillInForm->new( parser_class => 'MyAlternate::Parser' );
162
164 Apache::PageKit
165 To use HTML::FillInForm in Apache::PageKit is easy. It is
166 automatically called for any page that includes a <form> tag. It can
167 be turned on or off by using the "fill_in_form" configuration option.
168 Apache::ASP v2.09 and above
170 HTML::FillInForm is now integrated with Apache::ASP. To activate, use
171 PerlSetVar FormFill 1
173 $Response->{FormFill} = 1
174 HTML::Mason
176 Using HTML::FillInForm from HTML::Mason is covered in the FAQ on the
177 masonhq.com website at
178 <http://www.masonhq.com/?FAQ:HTTPAndHTML#h-how_can_i_populate_form_values_automatically_>
179
181 This documentation describes HTML::FillInForm module version 2.1
182
184 Note that you might want to think about caching issues if you have
185 password fields on your page. There is a discussion of this issue at
186 http://www.perlmonks.org/index.pl?node_id=70482
188 In summary, some browsers will cache the output of CGI scripts, and you
190 can control this by setting the Expires header. For example, use
191 "-expires" in CGI.pm or set "browser_cache" to no in Config.xml file of
192 Apache::PageKit.
193
195 Kato Atsushi has translated these docs into Japanese, available from
196 http://perldoc.jp
198
200 Please submit any bug reports to tjmather@maxmind.com.
201
203 Requires Perl 5.005 and HTML::Parser version 3.26.
204 I wrote this module because I wanted to be able to insert CGI data into
206 HTML forms, but without combining the HTML and Perl code. CGI.pm and
207 Embperl allow you so insert CGI data into forms, but require that you
208 mix HTML with Perl.
209 There is a nice review of the module available here:
211 <http://www.perlmonks.org/index.pl?node_id=274534>
212
214 (c) 2011 TJ Mather, tjmather@maxmind.com, <http://www.maxmind.com/>
215 All rights reserved. This package is free software; you can
217 redistribute it and/or modify it under the same terms as Perl itself.
218
220 HTML::Parser, Data::FormValidator, HTML::Template, Apache::PageKit
221
223 Fixes, Bug Reports, Docs have been generously provided by:
224 Alex Kapranoff Miika Pekkarinen
226 Michael Fisher Sam Tregar
227 Tatsuhiko Miyagawa Joseph Yanni
228 Boris Zentner Philip Mak
229 Dave Rolsky Jost Krieger
230 Patrick Michael Kane Gabriel Burka
231 Ade Olonoh Bill Moseley
232 Tom Lancaster James Tolley
233 Martin H Sluka Dan Kubb
234 Mark Stosberg Alexander Hartmaier
235 Jonathan Swartz Paul Miller
236 Trevor Schellhorn Anthony Ettinger
237 Jim Miner Simon P. Ditner
238 Paul Lindner Michael Peters
239 Maurice Aubrey Trevor Schellhorn
240 Andrew Creer
241 Thanks!
243perl v5.28.0 2014-08-14 HTML::FillInForm(3)