1CGI::Ex::Fill(3) User Contributed Perl Documentation CGI::Ex::Fill(3)
2
6 CGI::Ex::Fill - Fast but compliant regex based form filler
7
9 use CGI::Ex::Fill qw(form_fill fill);
10 my $text = my_own_template_from_somewhere();
12 my $form = CGI->new;
14 # OR
15 # my $form = {key => 'value'}
16 # OR
17 # my $form = [CGI->new, CGI->new, {key1 => 'val1'}, CGI->new];
18 form_fill(\$text, $form); # modifies $text
20 # OR
22 # my $copy = form_fill($text, $form); # copies $text
23 # OR
25 fill({
26 text => \$text,
27 form => $form,
28 });
29 # ALSO
31 my $formname = 'formname'; # form to parse (undef = anytable)
33 my $fp = 0; # fill_passwords ? default is true
34 my $ignore = ['key1', 'key2']; # OR {key1 => 1, key2 => 1};
35 form_fill(\$text, $form, $formname, $fp, $ignore);
37 # OR
39 fill({
40 text => \$text,
41 form => $form,
42 target => 'my_formname',
43 fill_password => $fp,
44 ignore_fields => $ignore,
45 });
46 # ALSO
48 ### delay getting the value until we find an element that needs it
50 my $form = {key => sub {my $key = shift; # get and return value}};
51
53 form_fill is directly comparable to HTML::FillInForm. It will pass the
54 same suite of tests (actually - it is a little bit kinder on the parse
55 as it won't change case, reorder your attributes, or alter miscella‐
56 neous spaces and it won't require the HTML to be well formed).
57 HTML::FillInForm is based upon HTML::Parser while CGI::Ex::Fill is
59 purely regex driven. The performance of CGI::Ex::Fill will be better
60 on HTML with many markup tags because HTML::Parser will parse each tag
61 while CGI::Ex::Fill will search only for those tags it knows how to
62 handle. And CGI::Ex::Fill generally won't break on malformed html.
63 On tiny forms (< 1 k) form_fill was ~ 13% slower than FillInForm. If
65 the html document incorporated very many entities at all, the perfor‐
66 mance of FillInForm goes down (adding 360 <br> tags pushed form_fill to
67 ~ 350% faster). However, if you are only filling in one form every so
68 often, then it shouldn't matter which you use - but form_fill will be
69 nicer on the tags and won't balk at ugly html and will decrease perfor‐
70 mance only at a slow rate as the size of the html increases. See the
71 benchmarks in the t/samples/bench_cgix_hfif.pl file for more informa‐
72 tion (ALL BENCHMARKS SHOULD BE TAKEN WITH A GRAIN OF SALT).
73 There are two functions, fill and form_fill. The function fill takes a
75 hashref of named arguments. The function form_fill takes a list of
76 positional parameters.
77
79 The following are the arguments to the main function "fill".
80 text
82 A reference to an html string that includes one or more forms.
83 form
85 A form hash, CGI object, or an array of hashrefs and objects.
86 target
88 The name of the form to swap. Default is undef which means to swap
89 all form entities in all forms.
90 fill_password
92 Default true. If set to false, fields of type password will not be
93 refilled.
94 ignore_fields
96 Hashref of fields to be ignored from swapping.
97 remove_script
99 Defaults to the package global $REMOVE_SCRIPT which defaults to
100 true. Removes anything in <script></script> tags which often cause
101 problems for parsers.
102 remove_comment
104 Defaults to the package global $REMOVE_COMMENT which defaults to
105 true. Removes anything in <!-- --> tags which can sometimes cause
106 problems for parsers.
107 object_method
109 The method to call on objects passed to the form argument. Default
110 value is the package global $OBJECT_METHOD which defaults to
111 'param'. If a CGI object is passed, it would call param on that
112 object passing the desired keyname as an argument.
113
115 The following are the arguments to the legacy function "form_fill".
116 "\$html"
118 A reference to an html string that includes one or more forms or
119 form entities.
120 "\%FORM"
122 A form hash, or CGI query object, or an arrayref of multiple hash
123 refs and/or CGI query objects that will supply values for the form.
124 $form_name
126 The name of the form to fill in values for. The default is undef
127 which indicates that all forms are to be filled in.
128 $swap_pass
130 Default true. Indicates that "<lt"input type="password"<gt>>
131 fields are to be swapped as well. Set to false to disable this
132 behavior.
133 "\%IGNORE_FIELDS" OR "\@IGNORE_FIELDS"
135 A hash ref of key names or an array ref of key names that will be
136 ignored during the fill in of the form.
137
139 fill and form_fill will attempt to DWYM when filling in values. The
140 following behaviors are used on the following types of form elements.
141 "<input type="text">"
143 The following rules are used when matching this type:
144 1) Get the value from the form that matches the input's "name".
146 2) If the value is defined - it adds or replaces the existing value.
147 3) If the value is not defined and the existing value is not defined,
148 a value of "" is added.
149 For example:
151 my $form = {foo => "FOO", bar => "BAR", baz => "BAZ"};
153 my $html = '
155 <input type=text name=foo>
156 <input type=text name=foo>
157 <input type=text name=bar value="">
158 <input type=text name=baz value="Something else">
159 <input type=text name=hem value="Another thing">
160 <input type=text name=haw>
161 ';
162 form_fill(\$html, $form);
164 $html eq '
166 <input type=text name=foo value="FOO">
167 <input type=text name=foo value="FOO">
168 <input type=text name=bar value="BAR">
169 <input type=text name=baz value="BAZ">
170 <input type=text name=hem value="Another thing">
171 <input type=text name=haw value="">
172 ';
173 If the value returned from the form is an array ref, the values of
175 the array ref will be sequentially used for each input found by
176 that name until the values run out. If the value is not an array
177 ref - it will be used to fill in any values by that name. For
178 example:
179 $form = {foo => ['aaaa', 'bbbb', 'cccc']};
181 $html = '
183 <input type=text name=foo>
184 <input type=text name=foo>
185 <input type=text name=foo>
186 <input type=text name=foo>
187 <input type=text name=foo>
188 ';
189 form_fill(\$html, $form);
191 $html eq '
193 <input type=text name=foo value="aaaa">
194 <input type=text name=foo value="bbbb">
195 <input type=text name=foo value="cccc">
196 <input type=text name=foo value="">
197 <input type=text name=foo value="">
198 ';
199 "<input type="hidden">"
201 Same as "<input type="text">".
202 "<input type="password">"
204 Same as "<input type="text">".
205 "<input type="file">"
207 Same as "<input type="text">". (Note - this is subject to browser
208 support for pre-population)
209 "<input type="checkbox">"
211 As each checkbox is found the following rules are applied:
212 1) Get the values from the form (do nothing if no values found)
214 2) Remove any existing "checked=checked" or "checked" markup from the tag.
215 3) Compare the "value" field to the values and mark with checked="checked"
216 if there is a match.
217 If no "value" field is found in the html, a default value of "on"
219 will be used (which is what most browsers will send as the default
220 value for checked boxes without "value" fields).
221 $form = {foo => 'FOO', bar => ['aaaa', 'bbbb', 'cccc'], baz => 'on'};
223 $html = '
225 <input type=checkbox name=foo value="123">
226 <input type=checkbox name=foo value="FOO">
227 <input type=checkbox name=bar value="aaaa">
228 <input type=checkbox name=bar value="cccc">
229 <input type=checkbox name=bar value="dddd" checked="checked">
230 <input type=checkbox name=baz>
231 ';
232 form_fill(\$html, $form);
234 $html eq '
236 <input type=checkbox name=foo value="123">
237 <input type=checkbox name=foo value="FOO" checked="checked">
238 <input type=checkbox name=bar value="aaaa" checked="checked">
239 <input type=checkbox name=bar value="cccc" checked="checked">
240 <input type=checkbox name=bar value="dddd">
241 <input type=checkbox name=baz checked="checked">
242 ';
243 "<input type="radio">"
245 Same as "<input type="checkbox">".
246 "<select>"
248 As each select box is found the following rules are applied (these
249 rules are applied regardless of if the box is a select-one or a
250 select-multi - if multiple values are selected on a select-one it
251 is up to the browser to choose which one to highlight):
252 1) Get the values from the form (do nothing if no values found)
254 2) Remove any existing "selected=selected" or "selected" markup from the tag.
255 3) Compare the "value" field to the values and mark with selected="selected"
256 if there is a match.
257 4) If there is no "value" field - use the text in between the "option" tags.
258 (Note: There does not need to be a closing "select" tag or closing "option" tag)
260 $form = {foo => 'FOO', bar => ['aaaa', 'bbbb', 'cccc']};
262 $html = '
264 <select name=foo><option>FOO<option>123<br>
265 <select name=bar>
267 <option>aaaa</option>
268 <option value="cccc">cccc</option>
269 <option value="dddd" selected="selected">dddd</option>
270 </select>
271 ';
272 form_fill(\$html, $form);
274 ok(
276 $html eq '
277 <select name=foo><option selected="selected">FOO<option>123<br>
278 <select name=bar>
280 <option selected="selected">aaaa</option>
281 <option value="cccc" selected="selected">cccc</option>
282 <option value="dddd">dddd</option>
283 </select>
284 ', "Perldoc example 4 passed");
285 "<textarea>"
287 The rules for swapping textarea are as follows:
288 1) Get the value from the form that matches the textarea's "name".
290 2) If the value is defined - it adds or replaces the existing value.
291 3) If the value is not defined, the text area is left alone.
292 (Note - there does not need to be a closing textarea tag. In the case of
294 a missing close textarea tag, the contents of the text area will be
295 assumed to be the start of the next textarea of the end of the document -
296 which ever comes sooner)
297 If the form returned an array ref of values, then these values will
299 be used sequentially each time a textarea by that name is found.
300 If a single value (not array ref) is found, that value will be used
301 for each textarea by that name.
302 For example.
304 $form = {foo => 'FOO', bar => ['aaaa', 'bbbb']};
306 $html = '
308 <textarea name=foo></textarea>
309 <textarea name=foo></textarea>
310 <textarea name=bar>
312 <textarea name=bar></textarea><br>
313 <textarea name=bar>dddd</textarea><br>
314 <textarea name=bar><br><br>
315 ';
316 form_fill(\$html, $form);
318 $html eq '
320 <textarea name=foo>FOO</textarea>
321 <textarea name=foo>FOO</textarea>
322 <textarea name=bar>aaaa<textarea name=bar>bbbb</textarea><br>
324 <textarea name=bar></textarea><br>
325 <textarea name=bar>';
326 "<input type="submit">"
328 Does nothing. The value for submit should typically be set by the
329 templating system or application system.
330 "<input type="button">"
332 Same as submit.
333
335 Because there are too many problems that could occur with html comments
336 and javascript, form_fill temporarily removes them during the fill.
337 You may disable this behavior by setting $REMOVE_COMMENT and
338 $REMOVE_SCRIPT to 0 before calling form_fill. The main reason for
339 doing this would be if you wanted to have form elements inside the
340 javascript and comments get filled. Disabling the removal only results
341 in a speed increase of 5%. The function uses \0COMMENT\0 and \0SCRIPT\0
342 as placeholders so it would be good to avoid these in your text (Actu‐
343 ally they may be reset to whatever you'd like via $MARKER_COMMENT and
344 $MARKER_SCRIPT).
345
347 "html_escape"
348 Very minimal entity escaper for filled in values.
349 my $escaped = html_escape($unescaped);
351 html_escape(\$text_to_escape);
353 "get_tagval_by_key"
355 Get a named value for from an html tag (key="value" pairs).
356 my $val = get_tagval_by_key(\$tag, $key);
358 my $valsref = get_tagval_by_key(\$tag, $key, 'all'); # get all values
359 "swap_tagval_by_key"
361 Swap out values in an html tag (key="value" pairs).
362 my $count = swap_tagval_by_key(\$tag, $key, $val); # modify ref
364 my $newtag = swap_tagval_by_key($tag, $key, $val); # copies tag
365
367 This module may distributed under the same terms as Perl itself.
368
370 Paul Seamons <perl at seamons dot com>
371perl v5.8.8 2007-10-18 CGI::Ex::Fill(3)