NAME

HTML::FillInForm::Lite - Fills in HTML forms with data

VERSION

The document describes HTML::FillInForm version 0.09

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); # yes, \&my_param is ok
        $output = $h->fill('t.html', [$q, \%default]);

        $output = $h->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);

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.

METHODS

new(options...)

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

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

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 <tag>.

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

You can suply 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.

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

If there are named entities in the fields and the option is true, HTML::Entities will be required.

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

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

Fills in source with form_data.

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() before fill().

To clear all the fields, provide form_data with a subroutine returning an empty string, like:

        HTML::FillInForm::Lite->fill($source, sub{ '' });

form_data as a subroutine is called in list context. That is, to leave some fields untouched, it must return (), not undef.

NOTES

Compatibility with HTML::FillInForm

This module implements only the new syntax of HTML::FillInForm version 2.

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 ommited 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 processible, 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 will process the code to be broken:

        <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 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 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.

cpanm HTML::FillInForm::Lite

perl -MCPAN -e shell
install HTML::FillInForm::Lite