Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::FillInForm(3)   User Contributed Perl Documentation  HTML::FillInForm(3)

NAME
       HTML::FillInForm	- Populates HTML Forms with data.

DESCRIPTION
       This module fills in an HTML form with data from	a Perl data structure,
       allowing	you to keep the	HTML and Perl separate.

       Here are	two common use cases:

       1. A user submits an HTML 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.

       2. You have just	retrieved a record from	a database and need to display
       it in an	HTML form.

SYNOPSIS
       Fill HTML form with data.

	 $output = HTML::FillInForm->fill( \$html,   $q	);
	 $output = HTML::FillInForm->fill( \@html,   [$q1,$q2] );
	 $output = HTML::FillInForm->fill( \*HTML,   \%data );
	 $output = HTML::FillInForm->fill( 't.html', [\%data1,%data2] );

       The HTML	can be provided	as a scalarref,	arrayref, filehandle or	file.
       The data	can come from one or more hashrefs, or objects which support a
       param() method, like CGI.pm, Apache::Request, etc.

fill
       The basic syntax	is seen	above the Synopsis. There are a	few additional
       options.

   Options
       target =_ 'form1'

       Suppose you have	multiple forms in a html file and only want to fill in
       one.

	 $output = HTML::FillInForm->fill(\$html, $q, target =>	'form1');

       This will fill in only the form inside

	 <FORM name="form1"> ... </FORM>

       fill_password =_	0

       Passwords are filled in by default. To disable:

	 fill_password => 0

       ignore_fields =_	[]

       To disable the filling of some fields:

	   ignore_fields => ['prev','next']

       disable_fields =_ []

       To disable fields from being edited:

	   disable_fields => [ 'uid', 'gid' ]

       invalid_fields =_ []

       To mark fields as being invalid (CSS class set to "invalid" or whatever
       you set invalid_class to):

	   invalid_fields => [ 'uid', 'gid' ]

       invalid_class =_	"invalid"

       The CSS class which will	be used	to mark	fields invalid.	 Defaults to
       "invalid".

       clear_absent_checkboxes =_ 0

       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.

       To remove "checked" attribute from checkboxes and radio buttons and
       attribute "selected" from options of select lists for which there's no
       data:

	   clear_absent_checkboxes => 1

   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.

   Clearing Fields
       Fields are cleared if you set their value to an empty string or empty
       arrayref	but not	undef:

	 # this	will leave the form element foo	untouched
	 HTML::FillInForm->fill(\$html,	{ foo => undef });

	 # this	will set clear the form	element	foo
	 HTML::FillInForm->fill(\$html,	{ foo => "" });

       It has been suggested to	add a option to	change the behavior so that
       undef values will clear the form	elements.  Patches welcome.

       You can also use	"clear_absent_checkboxes" option to clear checkboxes,
       radio buttons and selects without corresponding keys in the data:

	   # this will set clear the form element foo (and all others except
	   # bar)
	   HTML::FillInForm->fill(\$html, { bar	=> 123 },
	       clear_absent_checkboxes => 1);

Old syntax
       You probably need to read no further. The remaining docs	concern	the
       1.x era syntax, which is	still supported.

   new
       Call "new()" to create a	new FillInForm object:

	 $fif =	HTML::FillInForm->new;
	 $fif->fill(...);

       In theory, there	is a slight performance	benefit	to calling "new()"
       before "fill()" if you make multiple calls to "fill()" before you
       destroy the object. Benchmark before optimizing.

   fill	( old syntax )
       Instead of having your HTML and data types auto-detected, you can
       declare them explicitly in your call to "fill()":

       HTML source options:

	   arrayref  =>	@html
	   scalarref =>	$html
	   file	     =>	\*HTML
	   file	     =>	't.html'

       Fill Data options:

	   fobject   =>	$data_obj  # with param() method
	   fdat	     =>	\%data

       Additional methods are also available:

	   fill_file(\*HTML,...);
	   fill_file('t.html',...);
	   fill_arrayref(\@html,...);
	   fill_scalarref(\$html,...);

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 "parser_class"
       to new();

	  HTML::FillInForm->new( parser_class => 'MyAlternate::Parser' );

CALLING	FROM OTHER MODULES
   Apache::PageKit
       To use HTML::FillInForm in Apache::PageKit is easy.   It	is
       automatically called for	any page that includes a <form>	tag.  It can
       be turned on or off by using the	"fill_in_form" configuration option.

   Apache::ASP v2.09 and above
       HTML::FillInForm	is now integrated with Apache::ASP.  To	activate, use

	 PerlSetVar FormFill 1
	 $Response->{FormFill} = 1

   HTML::Mason
       Using HTML::FillInForm from HTML::Mason is covered in the FAQ on	the
       masonhq.com website at
       <http://www.masonhq.com/?FAQ:HTTPAndHTML#h-how_can_i_populate_form_values_automatically_>

VERSION
       This documentation describes HTML::FillInForm module version 2.1

SECURITY
       Note that you might want	to think about caching issues if you have
       password	fields on your page.  There is a discussion of this issue at

       http://www.perlmonks.org/index.pl?node_id=70482

       In summary, some	browsers will cache the	output of CGI scripts, and you
       can control this	by setting the Expires header.	For example, use
       "-expires" in CGI.pm or set "browser_cache" to no in Config.xml file of
       Apache::PageKit.

TRANSLATION
       Kato Atsushi has	translated these docs into Japanese, available from

       http://perldoc.jp

BUGS
       Please submit any bug reports to	tjmather@maxmind.com.

NOTES
       Requires	Perl 5.005 and HTML::Parser version 3.26.

       I wrote this module because I wanted to be able to insert CGI data into
       HTML forms, but without combining the HTML and Perl code.  CGI.pm and
       Embperl allow you so insert CGI data into forms,	but require that you
       mix HTML	with Perl.

       There is	a nice review of the module available here:
       <http://www.perlmonks.org/index.pl?node_id=274534>

AUTHOR
       (c) 2011	TJ Mather, tjmather@maxmind.com, <http://www.maxmind.com/>

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

SEE ALSO
       HTML::Parser, Data::FormValidator, HTML::Template, Apache::PageKit

CREDITS
       Fixes, Bug Reports, Docs	have been generously provided by:

	 Alex Kapranoff		       Miika Pekkarinen
	 Michael Fisher		       Sam Tregar
	 Tatsuhiko Miyagawa	       Joseph Yanni
	 Boris Zentner		       Philip Mak
	 Dave Rolsky		       Jost Krieger
	 Patrick Michael Kane	       Gabriel Burka
	 Ade Olonoh		       Bill Moseley
	 Tom Lancaster		       James Tolley
	 Martin	H Sluka		       Dan Kubb
	 Mark Stosberg		       Alexander Hartmaier
	 Jonathan Swartz	       Paul Miller
	 Trevor	Schellhorn	       Anthony Ettinger
	 Jim Miner		       Simon P.	Ditner
	 Paul Lindner		       Michael Peters
	 Maurice Aubrey		       Trevor Schellhorn
	 Andrew	Creer

       Thanks!

perl v5.32.0			  2014-08-14		   HTML::FillInForm(3)

NAME | DESCRIPTION | SYNOPSIS | fill | Old syntax | USING AN ALTERNATE PARSER | CALLING FROM OTHER MODULES | VERSION | SECURITY | TRANSLATION | BUGS | NOTES | AUTHOR | SEE ALSO | CREDITS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::FillInForm&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help