HTML::FillInForm - phpMan

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

VERSION
    version 2.22

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.

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.

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_value
    s_automatically_>

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

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!

AUTHOR
    TJ Mather, tjmather AT maxmind.com

COPYRIGHT AND LICENSE
    This software is copyright (c) 2000 by TJ Mather, tjmather AT maxmind.com.

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