1CGI::Ex::Fill(3)      User Contributed Perl Documentation     CGI::Ex::Fill(3)
2
3
4

NAME

6       CGI::Ex::Fill - Fast but compliant regex based form filler
7

SYNOPSIS

9           use CGI::Ex::Fill qw(form_fill fill);
10
11           my $text = my_own_template_from_somewhere();
12
13           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
19
20           form_fill(\$text, $form); # modifies $text
21
22           # OR
23           # my $copy = form_fill($text, $form); # copies $text
24
25           # OR
26           fill({
27               text => \$text,
28               form => $form,
29           });
30
31
32           # ALSO
33
34           my $formname = 'formname';     # form to parse (undef = anytable)
35           my $fp = 0;                    # fill_passwords ? default is true
36           my $ignore = ['key1', 'key2']; # OR {key1 => 1, key2 => 1};
37
38           form_fill(\$text, $form, $formname, $fp, $ignore);
39
40           # OR
41           fill({
42               text          => \$text,
43               form          => $form,
44               target        => 'my_formname',
45               fill_password => $fp,
46               ignore_fields => $ignore,
47           });
48
49           # ALSO
50
51           ### delay getting the value until we find an element that needs it
52           my $form = {key => sub {my $key = shift; # get and return value}};
53

DESCRIPTION

55       form_fill is directly comparable to HTML::FillInForm.  It will pass the
56       same suite of tests (actually - it is a little bit kinder on the parse
57       as it won't change case, reorder your attributes, or alter
58       miscellaneous spaces and it won't require the HTML to be well formed).
59
60       HTML::FillInForm is based upon HTML::Parser while CGI::Ex::Fill is
61       purely regex driven.  The performance of CGI::Ex::Fill will be better
62       on HTML with many markup tags because HTML::Parser will parse each tag
63       while CGI::Ex::Fill will search only for those tags it knows how to
64       handle.  And CGI::Ex::Fill generally won't break on malformed html.
65
66       On tiny forms (< 1 k) form_fill was ~ 13% slower than FillInForm.  If
67       the html document incorporated very many entities at all, the
68       performance of FillInForm goes down (adding 360 <br> tags pushed
69       form_fill to ~ 350% faster).  However, if you are only filling in one
70       form every so often, then it shouldn't matter which you use - but
71       form_fill will be nicer on the tags and won't balk at ugly html and
72       will decrease performance only at a slow rate as the size of the html
73       increases.  See the benchmarks in the t/samples/bench_cgix_hfif.pl file
74       for more information (ALL BENCHMARKS SHOULD BE TAKEN WITH A GRAIN OF
75       SALT).
76
77       There are two functions, fill and form_fill.  The function fill takes a
78       hashref of named arguments.  The function form_fill takes a list of
79       positional parameters.
80

ARGUMENTS TO form_fill

82       The following are the arguments to the main function "fill".
83
84       text
85           A reference to an html string that includes one or more forms.
86
87       form
88           A form hash, CGI object, or an array of hashrefs and objects.
89
90       target
91           The name of the form to swap.  Default is undef which means to swap
92           all form entities in all forms.
93
94       fill_password
95           Default true.  If set to false, fields of type password will not be
96           refilled.
97
98       ignore_fields
99           Hashref of fields to be ignored from swapping.
100
101       remove_script
102           Defaults to the package global $REMOVE_SCRIPT which defaults to
103           true.  Removes anything in <script></script> tags which often cause
104           problems for parsers.
105
106       remove_comment
107           Defaults to the package global $REMOVE_COMMENT which defaults to
108           true.  Removes anything in <!-- --> tags which can sometimes cause
109           problems for parsers.
110
111       object_method
112           The method to call on objects passed to the form argument.  Default
113           value is the package global $OBJECT_METHOD which defaults to
114           'param'.  If a CGI object is passed, it would call param on that
115           object passing the desired keyname as an argument.
116

ARGUMENTS TO form_fill

118       The following are the arguments to the legacy function "form_fill".
119
120       "\$html"
121           A reference to an html string that includes one or more forms or
122           form entities.
123
124       "\%FORM"
125           A form hash, or CGI query object, or an arrayref of multiple hash
126           refs and/or CGI query objects that will supply values for the form.
127
128       $form_name
129           The name of the form to fill in values for.  The default is undef
130           which indicates that all forms are to be filled in.
131
132       $swap_pass
133           Default true.  Indicates that "<lt"input type="password"<gt>>
134           fields are to be swapped as well.  Set to false to disable this
135           behavior.
136
137       "\%IGNORE_FIELDS" OR "\@IGNORE_FIELDS"
138           A hash ref of key names or an array ref of key names that will be
139           ignored during the fill in of the form.
140

BEHAVIOR

142       fill and form_fill will attempt to DWYM when filling in values.  The
143       following behaviors are used on the following types of form elements.
144
145       "<input type="text">"
146           The following rules are used when matching this type:
147
148              1) Get the value from the form that matches the input's "name".
149              2) If the value is defined - it adds or replaces the existing value.
150              3) If the value is not defined and the existing value is not defined,
151                 a value of "" is added.
152
153           For example:
154
155              my $form = {foo => "FOO", bar => "BAR", baz => "BAZ"};
156
157              my $html = '
158                  <input type=text name=foo>
159                  <input type=text name=foo>
160                  <input type=text name=bar value="">
161                  <input type=text name=baz value="Something else">
162                  <input type=text name=hem value="Another thing">
163                  <input type=text name=haw>
164              ';
165
166              form_fill(\$html, $form);
167
168              $html eq   '
169                  <input type=text name=foo value="FOO">
170                  <input type=text name=foo value="FOO">
171                  <input type=text name=bar value="BAR">
172                  <input type=text name=baz value="BAZ">
173                  <input type=text name=hem value="Another thing">
174                  <input type=text name=haw value="">
175              ';
176
177           If the value returned from the form is an array ref, the values of
178           the array ref will be sequentially used for each input found by
179           that name until the values run out.  If the value is not an array
180           ref - it will be used to fill in any values by that name.  For
181           example:
182
183              $form = {foo => ['aaaa', 'bbbb', 'cccc']};
184
185              $html = '
186                  <input type=text name=foo>
187                  <input type=text name=foo>
188                  <input type=text name=foo>
189                  <input type=text name=foo>
190                  <input type=text name=foo>
191              ';
192
193              form_fill(\$html, $form);
194
195              $html eq  '
196                  <input type=text name=foo value="aaaa">
197                  <input type=text name=foo value="bbbb">
198                  <input type=text name=foo value="cccc">
199                  <input type=text name=foo value="">
200                  <input type=text name=foo value="">
201              ';
202
203       "<input type="hidden">"
204           Same as "<input type="text">".
205
206       "<input type="password">"
207           Same as "<input type="text">".
208
209       "<input type="file">"
210           Same as "<input type="text">".  (Note - this is subject to browser
211           support for pre-population)
212
213       "<input type="checkbox">"
214           As each checkbox is found the following rules are applied:
215
216               1) Get the values from the form (do nothing if no values found)
217               2) Remove any existing "checked=checked" or "checked" markup from the tag.
218               3) Compare the "value" field to the values and mark with checked="checked"
219               if there is a match.
220
221           If no "value" field is found in the html, a default value of "on"
222           will be used (which is what most browsers will send as the default
223           value for checked boxes without "value" fields).
224
225              $form = {foo => 'FOO', bar => ['aaaa', 'bbbb', 'cccc'], baz => 'on'};
226
227              $html = '
228                  <input type=checkbox name=foo value="123">
229                  <input type=checkbox name=foo value="FOO">
230                  <input type=checkbox name=bar value="aaaa">
231                  <input type=checkbox name=bar value="cccc">
232                  <input type=checkbox name=bar value="dddd" checked="checked">
233                  <input type=checkbox name=baz>
234              ';
235
236              form_fill(\$html, $form);
237
238              $html eq  '
239                  <input type=checkbox name=foo value="123">
240                  <input type=checkbox name=foo value="FOO" checked="checked">
241                  <input type=checkbox name=bar value="aaaa" checked="checked">
242                  <input type=checkbox name=bar value="cccc" checked="checked">
243                  <input type=checkbox name=bar value="dddd">
244                  <input type=checkbox name=baz checked="checked">
245              ';
246
247       "<input type="radio">"
248           Same as "<input type="checkbox">".
249
250       "<select>"
251           As each select box is found the following rules are applied (these
252           rules are applied regardless of if the box is a select-one or a
253           select-multi - if multiple values are selected on a select-one it
254           is up to the browser to choose which one to highlight):
255
256               1) Get the values from the form (do nothing if no values found)
257               2) Remove any existing "selected=selected" or "selected" markup from the tag.
258               3) Compare the "value" field to the values and mark with selected="selected"
259               if there is a match.
260               4) If there is no "value" field - use the text in between the "option" tags.
261
262               (Note: There does not need to be a closing "select" tag or closing "option" tag)
263
264
265              $form = {foo => 'FOO', bar => ['aaaa', 'bbbb', 'cccc']};
266
267              $html = '
268                  <select name=foo><option>FOO<option>123<br>
269
270                  <select name=bar>
271                    <option>aaaa</option>
272                    <option value="cccc">cccc</option>
273                    <option value="dddd" selected="selected">dddd</option>
274                  </select>
275              ';
276
277              form_fill(\$html, $form);
278
279              ok(
280              $html eq  '
281                  <select name=foo><option selected="selected">FOO<option>123<br>
282
283                  <select name=bar>
284                    <option selected="selected">aaaa</option>
285                    <option value="cccc" selected="selected">cccc</option>
286                    <option value="dddd">dddd</option>
287                  </select>
288              ', "Perldoc example 4 passed");
289
290       "<textarea>"
291           The rules for swapping textarea are as follows:
292
293              1) Get the value from the form that matches the textarea's "name".
294              2) If the value is defined - it adds or replaces the existing value.
295              3) If the value is not defined, the text area is left alone.
296
297              (Note - there does not need to be a closing textarea tag.  In the case of
298               a missing close textarea tag, the contents of the text area will be
299               assumed to be the start of the next textarea of the end of the document -
300               which ever comes sooner)
301
302           If the form returned an array ref of values, then these values will
303           be used sequentially each time a textarea by that name is found.
304           If a single value (not array ref) is found, that value will be used
305           for each textarea by that name.
306
307           For example.
308
309              $form = {foo => 'FOO', bar => ['aaaa', 'bbbb']};
310
311              $html = '
312                  <textarea name=foo></textarea>
313                  <textarea name=foo></textarea>
314
315                  <textarea name=bar>
316                  <textarea name=bar></textarea><br>
317                  <textarea name=bar>dddd</textarea><br>
318                  <textarea name=bar><br><br>
319              ';
320
321              form_fill(\$html, $form);
322
323              $html eq  '
324                  <textarea name=foo>FOO</textarea>
325                  <textarea name=foo>FOO</textarea>
326
327                  <textarea name=bar>aaaa<textarea name=bar>bbbb</textarea><br>
328                  <textarea name=bar></textarea><br>
329                  <textarea name=bar>';
330
331       "<input type="submit">"
332           Does nothing.  The value for submit should typically be set by the
333           templating system or application system.
334
335       "<input type="button">"
336           Same as submit.
337

HTML COMMENT / JAVASCRIPT

339       Because there are too many problems that could occur with html comments
340       and javascript, form_fill temporarily removes them during the fill.
341       You may disable this behavior by setting $REMOVE_COMMENT and
342       $REMOVE_SCRIPT to 0 before calling form_fill.  The main reason for
343       doing this would be if you wanted to have form elements inside the
344       javascript and comments get filled.  Disabling the removal only results
345       in a speed increase of 5%. The function uses \0COMMENT\0 and \0SCRIPT\0
346       as placeholders so it would be good to avoid these in your text
347       (Actually they may be reset to whatever you'd like via $MARKER_COMMENT
348       and $MARKER_SCRIPT).
349

UTILITY FUNCTIONS

351       "html_escape"
352           Very minimal entity escaper for filled in values.
353
354               my $escaped = html_escape($unescaped);
355
356               html_escape(\$text_to_escape);
357
358       "get_tagval_by_key"
359           Get a named value for from an html tag (key="value" pairs).
360
361               my $val     = get_tagval_by_key(\$tag, $key);
362               my $valsref = get_tagval_by_key(\$tag, $key, 'all'); # get all values
363
364       "swap_tagval_by_key"
365           Swap out values in an html tag (key="value" pairs).
366
367               my $count  = swap_tagval_by_key(\$tag, $key, $val); # modify ref
368               my $newtag = swap_tagval_by_key($tag, $key, $val);  # copies tag
369

LICENSE

371       This module may distributed under the same terms as Perl itself.
372

AUTHOR

374       Paul Seamons <perl at seamons dot com>
375
376
377
378perl v5.12.1                      2010-02-25                  CGI::Ex::Fill(3)
Impressum