1# NAME
2
3HTML::FillInForm::Lite - Lightweight FillInForm module in Pure Perl
4
5# VERSION
6
7The document describes HTML::FillInForm::Lite version 1.13
8
9# SYNOPSIS
10
11    use HTML::FillInForm::Lite;
12    use CGI;
13
14    my $q = CGI->new();
15    my $h = HTML::FillInForm::Lite->new();
16
17    $output = $h->fill(\$html,    $q);
18    $output = $h->fill(\@html,    \%data);
19    $output = $h->fill(\*HTML,    \&my_param);
20    $output = $h->fill('t.html', [$q, \%default]);
21
22    # or as a class method with options
23    $output = HTML::FillInForm::Lite->fill(\$html, $q,
24        fill_password => 0, # it is default
25        ignore_fields => ['foo', 'bar'],
26        target        => $form_id,
27    );
28
29    # Moreover, it accepts any object as form data
30    # (these classes come form Class::DBI's SYNOPSIS)
31
32    my $artist = Music::Artist->insert({ id => 1, name => 'U2' });
33    $output = $h->fill(\$html, $artist);
34
35    my $cd = Music::CD->retrieve(1);
36    $output = $h->fill(\$html, $cd);
37
38    # simple function interface
39    use HTML::FillInForm::Lite qw(fillinform);
40
41    # the same as HTML::FillInForm::Lite->fill(...)
42    $output = fillinform(\$html, $q);
43
44# DESCRIPTION
45
46This module fills in HTML forms with Perl data,
47which re-implements `HTML::FillInForm` using regexp-based parser,
48not using `HTML::Parser`.
49
50The difference in the parsers makes `HTML::FillInForm::Lite` about 2
51times faster than `HTML::FillInForm`.
52
53# FUNCTIONS
54
55## fillinform(source, form\_data)
56
57Simple interface to the `fill()` method, accepting only a string.
58If you pass a single argument to this function, it is interpreted as
59_form\_data_, and returns a function that accepts _source_.
60
61    my $fillinform = fillinform($query);
62    $fillinform->($html); # the same as fillinform($html, $query)
63
64This function is exportable.
65
66# METHODS
67
68## new(options...)
69
70Creates `HTML::FillInForm::Lite` processor with _options_.
71
72There are several options. All the options are disabled when `undef` is
73supplied.
74
75Acceptable options are as follows:
76
77- fill\_password => _bool_
78
79    To enable passwords to be filled in, set the option true.
80
81    Note that the effect of the option is the same as that of `HTML::FillInForm`,
82    but by default `HTML::FillInForm::Lite` ignores password fields.
83
84- ignore\_fields => _array\_ref\_of\_fields_
85
86    To ignore some fields from filling.
87
88- target => _form\_id_
89
90    To fill in just the form identified by _form\_id_.
91
92- escape => _bool_ | _ref_
93
94    If true is provided (or by default), values filled in text fields will be
95    HTML-escaped, e.g. `<tag>` to be `&lt;tag&gt;`.
96
97    If the values are already HTML-escaped, set the option false.
98
99    You can supply a subroutine reference to escape the values.
100
101    Note that it is not implemented in `HTML::FillInForm`.
102
103- decode\_entity => _bool_ | _ref_
104
105    If true is provided , HTML entities in state fields
106    (namely, `radio`, `checkbox` and `select`) will be decoded,
107    but normally it is not needed.
108
109    You can also supply a subroutine reference to decode HTML entities.
110
111    Note that `HTML::FillInForm` always decodes HTML entities in state fields,
112    but not supports this option.
113
114- layer => _:iolayer_
115
116    To read a file with _:iolayer_. It is used when a file name is supplied as
117    _source_.
118
119    For example:
120
121        # To read a file encoded in UTF-8
122        $fif = HTML::FillInForm::Lite->new(layer => ':utf8');
123        $output = $fif->fill($utf8_file, $fdat);
124
125        # To read a file encoded in EUC-JP
126        $fif = HTML::FillInForm::Lite->new(layer => ':encoding(euc-jp)');
127        $output = $fif->fill($eucjp_file, $fdat);
128
129    Note that it is not implemented in `HTML::FillInForm`.
130
131## fill(source, form\_data \[, options...\])
132
133Fills in _source_ with _form\_data_. If _source_ or _form\_data_ is not
134supplied, it will cause `die`.
135
136_options_ are the same as `new()`'s.
137
138You can use this method as a both class or instance method,
139but you make multiple calls to `fill()` with the __same__
140options, it is a little faster to call `new()` and store the instance.
141
142_source_ may be a scalar reference, an array reference of strings, or
143a file name.
144
145_form\_data_ may be a hash reference, an object with `param()` method,
146an object with accessors, a code reference, or an array reference of
147those above mentioned.
148
149If _form\_data_ is based on procedures (i.e. not a hash reference),
150the procedures will be called in the list context.
151Therefore, to leave some fields untouched, it must return a null list `()`,
152not `undef`.
153
154# DEPENDENCIES
155
156Perl 5.8.1 or later.
157
158# NOTES
159
160## Compatibility with `HTML::FillInForm`
161
162This module implements only the new syntax of `HTML::FillInForm`
163version 2. However, `HTML::FillInForm::Lite::Compat` provides
164an interface compatible with `HTML::FillInForm`.
165
166## Compatibility with legacy HTML
167
168This module is designed to process XHTML 1.x.
169
170And it also supporting a good part of HTML 4.x , but there are some
171limitations. First, it doesn't understand HTML-attributes that the name is
172omitted.
173
174For example:
175
176    <INPUT TYPE=checkbox NAME=foo CHECKED> -- NG.
177    <INPUT TYPE=checkbox NAME=foo CHECKED=checked> - OK, but obsolete.
178    <input type="checkbox" name="foo" checked="checked" /> - OK, valid XHTML
179
180Then, it always treats the values of attributes case-sensitively.
181In the example above, the value of `type` must be lower-case.
182
183Moreover, it doesn't recognize omitted closing tags, like:
184
185    <select name="foo">
186        <option>bar
187        <option>baz
188    </select>
189
190When you can't get what you want, try to give your source to a HTML lint.
191
192## Comment handling
193
194This module processes all the processable, not knowing comments
195nor something that shouldn't be processed.
196
197It may cause problems. Suppose there is a code like:
198
199    <script> document.write("<input name='foo' />") </script>
200
201`HTML::FillInForm::Lite` will break the code:
202
203    <script> document.write("<input name='foo' value="bar" />") </script>
204
205To avoid such problems, you can use the `ignore_fields` option.
206
207# BUGS
208
209No bugs have been reported.
210
211Please report any bug or feature request to <gfuji(at)cpan.org>,
212or through the RT [http://rt.cpan.org/](http://rt.cpan.org/).
213
214# SEE ALSO
215
216[HTML::FillInForm](http://search.cpan.org/perldoc?HTML::FillInForm).
217
218[HTML::FillInForm::Lite::JA](http://search.cpan.org/perldoc?HTML::FillInForm::Lite::JA) - the document in Japanese.
219
220[HTML::FillInForm::Lite::Compat](http://search.cpan.org/perldoc?HTML::FillInForm::Lite::Compat) - HTML::FillInForm compatibility layer
221
222# AUTHOR
223
224Goro Fuji (藤 吾郎) <gfuji(at)cpan.org>
225
226# LICENSE AND COPYRIGHT
227
228Copyright (c) 2008-2010 Goro Fuji, Some rights reserved.
229
230This program is free software; you can redistribute it and/or modify it
231under the same terms as Perl itself.
232