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

NAME

6       HTML::FillInForm - Populates HTML Forms with data.
7

DESCRIPTION

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
12       Here are two common use cases:
13
14       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
18       2. You have just retrieved a record from a database and need to display
19       it in an HTML form.
20

SYNOPSIS

22       Fill HTML form with data.
23
24         $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
29       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

fill

34       The basic syntax is seen above the Synopsis. There are a few additional
35       options.
36
37   Options
38       target => 'form1'
39
40       Suppose you have multiple forms in a html file and only want to fill in
41       one.
42
43         $output = HTML::FillInForm->fill(\$html, $q, target => 'form1');
44
45       This will fill in only the form inside
46
47         <FORM name="form1"> ... </FORM>
48
49       fill_password => 0
50
51       Passwords are filled in by default. To disable:
52
53         fill_password => 0
54
55       ignore_fields => []
56
57       To disable the filling of some fields:
58
59           ignore_fields => ['prev','next']
60
61       disable_fields => []
62
63       To disable fields from being edited:
64
65           disable_fields => [ 'uid', 'gid' ]
66
67       invalid_fields => []
68
69       To mark fields as being invalid (CSS class set to "invalid" or whatever
70       you set invalid_class to):
71
72           invalid_fields => [ 'uid', 'gid' ]
73
74       invalid_class => "invalid"
75
76       The CSS class which will be used to mark fields invalid.  Defaults to
77       "invalid".
78
79       clear_absent_checkboxes => 0
80
81       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
85       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
89           clear_absent_checkboxes => 1
90
91   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
96   Clearing Fields
97       Fields are cleared if you set their value to an empty string or empty
98       arrayref but not undef:
99
100         # this will leave the form element foo untouched
101         HTML::FillInForm->fill(\$html, { foo => undef });
102
103         # this will set clear the form element foo
104         HTML::FillInForm->fill(\$html, { foo => "" });
105
106       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
109       You can also use "clear_absent_checkboxes" option to clear checkboxes,
110       radio buttons and selects without corresponding keys in the data:
111
112           # 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

Old syntax

118       You probably need to read no further. The remaining docs concern the
119       1.x era syntax, which is still supported.
120
121   new
122       Call "new()" to create a new FillInForm object:
123
124         $fif = HTML::FillInForm->new;
125         $fif->fill(...);
126
127       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
131   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
135       HTML source options:
136
137           arrayref  => @html
138           scalarref => $html
139           file      => \*HTML
140           file      => 't.html'
141
142       Fill Data options:
143
144           fobject   => $data_obj  # with param() method
145           fdat      => \%data
146
147       Additional methods are also available:
148
149           fill_file(\*HTML,...);
150           fill_file('t.html',...);
151           fill_arrayref(\@html,...);
152           fill_scalarref(\$html,...);
153

USING AN ALTERNATE PARSER

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
161          HTML::FillInForm->new( parser_class => 'MyAlternate::Parser' );
162

CALLING FROM OTHER MODULES

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
169   Apache::ASP v2.09 and above
170       HTML::FillInForm is now integrated with Apache::ASP.  To activate, use
171
172         PerlSetVar FormFill 1
173         $Response->{FormFill} = 1
174
175   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

VERSION

181       This documentation describes HTML::FillInForm module version 2.1
182

SECURITY

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
187       http://www.perlmonks.org/index.pl?node_id=70482
188
189       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

TRANSLATION

195       Kato Atsushi has translated these docs into Japanese, available from
196
197       http://perldoc.jp
198

BUGS

200       Please submit any bug reports to tjmather@maxmind.com.
201

NOTES

203       Requires Perl 5.005 and HTML::Parser version 3.26.
204
205       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
210       There is a nice review of the module available here:
211       <http://www.perlmonks.org/index.pl?node_id=274534>
212

AUTHOR

214       (c) 2011 TJ Mather, tjmather@maxmind.com, <http://www.maxmind.com/>
215
216       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

SEE ALSO

220       HTML::Parser, Data::FormValidator, HTML::Template, Apache::PageKit
221

CREDITS

223       Fixes, Bug Reports, Docs have been generously provided by:
224
225         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
242       Thanks!
243
244
245
246perl v5.28.1                      2014-08-14               HTML::FillInForm(3)
Impressum