.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::FillInForm 3pm"
.TH HTML::FillInForm 3pm "2021-09-29" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::FillInForm \- Populates HTML Forms with data.
.SH "VERSION"
.IX Header "VERSION"
version 2.22
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Fill \s-1HTML\s0 form with data.
.PP
.Vb 4
\& $output = HTML::FillInForm\->fill( \e$html, $q );
\& $output = HTML::FillInForm\->fill( \e@html, [$q1,$q2] );
\& $output = HTML::FillInForm\->fill( \e*HTML, \e%data );
\& $output = HTML::FillInForm\->fill( \*(Aqt.html\*(Aq, [\e%data1,%data2] );
.Ve
.PP
The \s-1HTML\s0 can be provided as a scalarref, arrayref, filehandle or file. The data can come from one or more
hashrefs, or objects which support a \fBparam()\fR method, like \s-1CGI\s0.pm, Apache::Request, etc.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module fills in an \s-1HTML\s0 form with data from a Perl data structure, allowing you
to keep the \s-1HTML\s0 and Perl separate.
.PP
Here are two common use cases:
.PP
1. A user submits an \s-1HTML\s0 form without filling out a required field. You want
to redisplay the form with all the previous data in it, to make it easy for the
user to see and correct the error.
.PP
2. You have just retrieved a record from a database and need to display it in
an \s-1HTML\s0 form.
.SH "fill"
.IX Header "fill"
The basic syntax is seen above the Synopsis. There are a few additional options.
.SS "Options"
.IX Subsection "Options"
\fItarget => 'form1'\fR
.IX Subsection "target => 'form1'"
.PP
Suppose you have multiple forms in a html file and only want to fill in one.
.PP
.Vb 1
\& $output = HTML::FillInForm\->fill(\e$html, $q, target => \*(Aqform1\*(Aq);
.Ve
.PP
This will fill in only the form inside
.PP
.Vb 1
\&
.Ve
.PP
\fIfill_password => 0\fR
.IX Subsection "fill_password => 0"
.PP
Passwords are filled in by default. To disable:
.PP
.Vb 1
\& fill_password => 0
.Ve
.PP
\fIignore_fields => []\fR
.IX Subsection "ignore_fields => []"
.PP
To disable the filling of some fields:
.PP
.Vb 1
\& ignore_fields => [\*(Aqprev\*(Aq,\*(Aqnext\*(Aq]
.Ve
.PP
\fIdisable_fields => []\fR
.IX Subsection "disable_fields => []"
.PP
To disable fields from being edited:
.PP
.Vb 1
\& disable_fields => [ \*(Aquid\*(Aq, \*(Aqgid\*(Aq ]
.Ve
.PP
\fIinvalid_fields => []\fR
.IX Subsection "invalid_fields => []"
.PP
To mark fields as being invalid (\s-1CSS\s0 class set to \*(L"invalid\*(R" or
whatever you set invalid_class to):
.PP
.Vb 1
\& invalid_fields => [ \*(Aquid\*(Aq, \*(Aqgid\*(Aq ]
.Ve
.PP
\fIinvalid_class => \*(L"invalid\*(R"\fR
.IX Subsection "invalid_class => invalid"
.PP
The \s-1CSS\s0 class which will be used to mark fields invalid. Defaults to
\&\*(L"invalid\*(R".
.PP
\fIclear_absent_checkboxes => 0\fR
.IX Subsection "clear_absent_checkboxes => 0"
.PP
Absent fields are not cleared or in any way changed. This is
not what you want when you deal with checkboxes which are not sent
by browser at all when cleared by user.
.PP
To remove \*(L"checked\*(R" attribute from checkboxes and radio buttons and
attribute \*(L"selected\*(R" from options of select lists for which there's no
data:
.PP
.Vb 1
\& clear_absent_checkboxes => 1
.Ve
.SS "File Upload fields"
.IX Subsection "File Upload fields"
File upload fields cannot be supported directly. Workarounds include asking the
user to re-attach any file uploads or fancy server-side storage and
referencing. You are on your own.
.SS "Clearing Fields"
.IX Subsection "Clearing Fields"
Fields are cleared if you set their value to an empty string or empty arrayref but not undef:
.PP
.Vb 2
\& # this will leave the form element foo untouched
\& HTML::FillInForm\->fill(\e$html, { foo => undef });
\&
\& # this will set clear the form element foo
\& HTML::FillInForm\->fill(\e$html, { foo => "" });
.Ve
.PP
It has been suggested to add a option to change the behavior so that undef
values will clear the form elements. Patches welcome.
.PP
You can also use \f(CW\*(C`clear_absent_checkboxes\*(C'\fR option to clear
checkboxes, radio buttons and selects without corresponding keys in
the data:
.PP
.Vb 4
\& # this will set clear the form element foo (and all others except
\& # bar)
\& HTML::FillInForm\->fill(\e$html, { bar => 123 },
\& clear_absent_checkboxes => 1);
.Ve
.SH "Old syntax"
.IX Header "Old syntax"
You probably need to read no further. The remaining docs concern the
1.x era syntax, which is still supported.
.SS "new"
.IX Subsection "new"
Call \f(CW\*(C`new()\*(C'\fR to create a new FillInForm object:
.PP
.Vb 2
\& $fif = HTML::FillInForm\->new;
\& $fif\->fill(...);
.Ve
.PP
In theory, there is a slight performance benefit to calling \f(CW\*(C`new()\*(C'\fR before \f(CW\*(C`fill()\*(C'\fR if you make multiple
calls to \f(CW\*(C`fill()\*(C'\fR before you destroy the object. Benchmark before optimizing.
.SS "fill ( old syntax )"
.IX Subsection "fill ( old syntax )"
Instead of having your \s-1HTML\s0 and data types auto-detected, you can declare them explicitly in your
call to \f(CW\*(C`fill()\*(C'\fR:
.PP
\&\s-1HTML\s0 source options:
.PP
.Vb 4
\& arrayref => @html
\& scalarref => $html
\& file => \e*HTML
\& file => \*(Aqt.html\*(Aq
.Ve
.PP
Fill Data options:
.PP
.Vb 2
\& fobject => $data_obj # with param() method
\& fdat => \e%data
.Ve
.PP
Additional methods are also available:
.PP
.Vb 4
\& fill_file(\e*HTML,...);
\& fill_file(\*(Aqt.html\*(Aq,...);
\& fill_arrayref(\e@html,...);
\& fill_scalarref(\e$html,...);
.Ve
.SH "USING AN ALTERNATE PARSER"
.IX Header "USING AN ALTERNATE PARSER"
It's possible to use an alternate parser to HTML::Parser if the alternate
provides a sufficiently compatible interface. For example, when a Pure Perl
implementation of HTML::Parser appears, it could be used for portability. The syntax
is simply to provide a \f(CW\*(C`parser_class\*(C'\fR to \fBnew()\fR;
.PP
.Vb 1
\& HTML::FillInForm\->new( parser_class => \*(AqMyAlternate::Parser\*(Aq );
.Ve
.SH "CALLING FROM OTHER MODULES"
.IX Header "CALLING FROM OTHER MODULES"
.SS "Apache::PageKit"
.IX Subsection "Apache::PageKit"
To use HTML::FillInForm in Apache::PageKit is easy. It is
automatically called for any page that includes a