HTML::FillInForm(3pm)

💖 HTML::FillInForm 💖

okay so bestie, you know how filling in HTML forms by hand is literally the worst? this module is the fix. it's HTML::FillInForm, version 2.22, and it's about to be your new fave. 🎀✨

---

✨ NAME ✨

HTML::FillInForm — Populates HTML Forms with data. 🫶 no cap.

---

🌸 VERSION 🌸

version 2.22 💅

---

🌈 SYNOPSIS 🌈

Fill HTML form with data. it's giving effortless. 💖

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

like. it just takes whatever you throw at it. iconic behavior honestly. 👑

---

💅 DESCRIPTION 💅

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

ngl, keeping those two apart is the whole point. it's a situationship-free zone. ✨

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.

both of these are so valid. 🥰

---

🦋 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. 😭 yeah bestie, this one's a solo mission.

🧹 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. 👀 (that's a hint, babe)

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. (vintage! retro! still slaying! 💜)

🌸 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. (in theory. THEORY. do not come for me. 😌)

🎀 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' );

plug in whatever parser you want, bestie. compatibility is the vibe check. ✨

---

💖 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_

---

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

okay real talk for a sec bestie — password fields + caching = 😬. go read that link.

---

🌸 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

---

🫶 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! 🥹💖 (yes Trevor is on there twice, he really showed up, we love that for him)

---

🌟 AUTHOR 🌟

TJ Mather, tjmather@maxmind.com

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2000 by TJ Mather, tjmather@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.

---

okay that's the whole page, bestie!! 💅 this was HTML::FillInForm(3pm), from perl v5.32.1, dated 2021-09-29 — go forth and fill in those forms, you absolute icon. 🌈✨💖