/ 
HTML-FillInForm-Lite-1.15
River stage one • 4 direct dependents • 4 total dependents
/ HTML::FillInForm::Lite

NAME

HTML::FillInForm::Lite - Lightweight FillInForm module in Pure Perl

VERSION

The document describes HTML::FillInForm::Lite version 1.15

SYNOPSIS

use HTML::FillInForm::Lite;
use CGI;

my $q = CGI->new();
my $h = HTML::FillInForm::Lite->new();

$output = $h->fill(\$html,    $q);
$output = $h->fill(\@html,    \%data);
$output = $h->fill(\*HTML,    \&my_param);
$output = $h->fill('t.html', [$q, \%default]);

# or as a class method with options
$output = HTML::FillInForm::Lite->fill(\$html, $q,
    fill_password => 0, # it is default
    ignore_fields => ['foo', 'bar'],
    target        => $form_id,
);

# Moreover, it accepts any object as form data
# (these classes come form Class::DBI's SYNOPSIS)

my $artist = Music::Artist->insert({ id => 1, name => 'U2' });
$output = $h->fill(\$html, $artist);

my $cd = Music::CD->retrieve(1);
$output = $h->fill(\$html, $cd);

# simple function interface
use HTML::FillInForm::Lite qw(fillinform);

# the same as HTML::FillInForm::Lite->fill(...)
$output = fillinform(\$html, $q);

DESCRIPTION

This module fills in HTML forms with Perl data, which re-implements HTML::FillInForm using regexp-based parser, not using HTML::Parser.

The difference in the parsers makes HTML::FillInForm::Lite about 2 times faster than HTML::FillInForm.

FUNCTIONS

fillinform(source, form_data)

Simple interface to the fill() method, accepting only a string. If you pass a single argument to this function, it is interpreted as form_data, and returns a function that accepts source.

my $fillinform = fillinform($query);
$fillinform->($html); # the same as fillinform($html, $query)

This function is exportable.

METHODS

new(options...)

Creates HTML::FillInForm::Lite processor with options.

There are several options. All the options are disabled when undef is supplied.

Acceptable options are as follows:

fill_password => bool

To enable passwords to be filled in, set the option true.

Note that the effect of the option is the same as that of HTML::FillInForm, but by default HTML::FillInForm::Lite ignores password fields.

ignore_fields => array_ref_of_fields

To ignore some fields from filling.

target => form_id

To fill in just the form identified by form_id.

escape => bool | ref

If true is provided (or by default), values filled in text fields will be HTML-escaped, e.g. <tag> to be &lt;tag&gt;.

If the values are already HTML-escaped, set the option false.

You can supply a subroutine reference to escape the values.

Note that it is not implemented in HTML::FillInForm.

decode_entity => bool | ref

If true is provided , HTML entities in state fields (namely, radio, checkbox and select) will be decoded, but normally it is not needed.

You can also supply a subroutine reference to decode HTML entities.

Note that HTML::FillInForm always decodes HTML entities in state fields, but not supports this option.

layer => :iolayer

To read a file with :iolayer. It is used when a file name is supplied as source.

For example:

# To read a file encoded in UTF-8
$fif = HTML::FillInForm::Lite->new(layer => ':utf8');
$output = $fif->fill($utf8_file, $fdat);

# To read a file encoded in EUC-JP
$fif = HTML::FillInForm::Lite->new(layer => ':encoding(euc-jp)');
$output = $fif->fill($eucjp_file, $fdat);

Note that it is not implemented in HTML::FillInForm.

fill(source, form_data [, options...])

Fills in source with form_data. If source or form_data is not supplied, it will cause die.

options are the same as new()'s.

You can use this method as a both class or instance method, but you make multiple calls to fill() with the same options, it is a little faster to call new() and store the instance.

source may be a scalar reference, an array reference of strings, or a file name.

form_data may be a hash reference, an object with param() method, an object with accessors, a code reference, or an array reference of those above mentioned.

If form_data is based on procedures (i.e. not a hash reference), the procedures will be called in the list context. Therefore, to leave some fields untouched, it must return a null list (), not undef.

DEPENDENCIES

Perl 5.8.1 or later.

NOTES

Compatibility with HTML::FillInForm

This module implements only the new syntax of HTML::FillInForm version 2. However, HTML::FillInForm::Lite::Compat provides an interface compatible with HTML::FillInForm.

Compatibility with legacy HTML

This module is designed to process XHTML 1.x.

And it also supporting a good part of HTML 4.x , but there are some limitations. First, it doesn't understand HTML-attributes that the name is omitted.

For example:

<INPUT TYPE=checkbox NAME=foo CHECKED> -- NG.
<INPUT TYPE=checkbox NAME=foo CHECKED=checked> - OK, but obsolete.
<input type="checkbox" name="foo" checked="checked" /> - OK, valid XHTML

Then, it always treats the values of attributes case-sensitively. In the example above, the value of type must be lower-case.

Moreover, it doesn't recognize omitted closing tags, like:

<select name="foo">
    <option>bar
    <option>baz
</select>

When you can't get what you want, try to give your source to a HTML lint.

Comment handling

This module processes all the processable, not knowing comments nor something that shouldn't be processed.

It may cause problems. Suppose there is a code like:

<script> document.write("<input name='foo' />") </script>

HTML::FillInForm::Lite will break the code:

<script> document.write("<input name='foo' value="bar" />") </script>

To avoid such problems, you can use the ignore_fields option.

BUGS

No bugs have been reported.

Please report any bug or feature request to <gfuji(at)cpan.org>, or through the RT http://rt.cpan.org/.

SEE ALSO

HTML::FillInForm.

HTML::FillInForm::Lite::JA - the document in Japanese.

HTML::FillInForm::Lite::Compat - HTML::FillInForm compatibility layer

AUTHOR

Goro Fuji (藤 吾郎) <gfuji(at)cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2008-2010 Goro Fuji, Some rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.