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

VERSION

9       version 2.50
10

SYNOPSIS

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

DESCRIPTION

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

ARGUMENTS TO form_fill

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

ARGUMENTS TO form_fill

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

BEHAVIOR

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

HTML COMMENT / JAVASCRIPT

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

UTILITY FUNCTIONS

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

LICENSE

374       This module may distributed under the same terms as Perl itself.
375

AUTHOR

377       Paul Seamons <perl at seamons dot com>
378
379
380
381perl v5.32.1                      2021-01-26                  CGI::Ex::Fill(3)
Impressum