HTML::Defaultify - Pre-fill default values into an existing HTML form
use HTML::Defaultify;
# $HTML is a block of HTML with a form, and %my_defaults is a hash of # values to populate the form with. # If $HTML contains multiple forms, you can name which form to populate. $new_HTML= &defaultify($HTML, \%my_defaults) ; $new_HTML= &defaultify($HTML, \%my_defaults, 'form1') ;
# If you care which defaults were left over, call it in list context. # Result can be passed to hidden_vars() to generate a set of # <input type=hidden> tags. ($new_HTML, $unused_defaults)= &defaultify($HTML, \%my_defaults) ; $remaining_form_values= &hidden_vars($unused_defaults) ;
# subhash() creates a hash that's a subset of a larger hash, similar # to a slice. Useful to partially populate forms. This example # might avoid filling in a "password" field. $new_HTML= &defaultify($HTML, &subhash(\%my_defaults, qw(login type))) ;
This module lets you take an existing HTML page with forms in it, and fill in the form fields according to defaults you give. It's most useful in CGI scripts. One common use is to handle invalid user input-- show them the same form with their previously entered values filled in, and let them correct any errors. Another use might be when letting users edit a database record, such as their account information-- show them an input form with the current values filled in. There are other uses.
Other tools can populate form fields, but they require the HTML and program source code to be highly intermingled. In contrast, the approach used here (of populating any existing HTML document) allows a clean separation of the HTML development and the programming. This works much better in projects where the two tasks are done by different people, such as a designer and a programmer.
To defaultify a form, use the defaultify() function. The following
command is all most people ever need from this module:
$new_HTML= &defaultify($HTML, $defaults) ;
or, to specify which form to defaultify on a page with multiple forms:
$new_HTML= &defaultify($HTML, $defaults, $form_name) ;
$HTML is some HTML text, possibly read in from a file; you might even
replace the parameter above with ```cat filename.html`''.
$defaults is a reference to a hash of default values-- the keys
of the hash correspond to the names of the form fields, and the values are
what to set the defaults to; each hash value may be either a scalar,
a reference to a list of scalars (for multiple input fields with the same
name), or a list in the form of a ``\0''-delimited scalar. $form_name is
the name of a form, from the ``name'' attribute of the <form> tag.
The resulting $new_HTML is the same as $HTML, except that all <input>
tags, <select>...</select> blocks, and <textarea>...</textarea> blocks have
been altered to best represent the values given in the defaults hash. This
includes clearing fields that have no default given. If $form_name is
given, changes are restricted to that form only. Otherwise, all of $HTML
is defaultified.
The format of the defaults hash is made to accommodate the most common ways
that form data sets are represented, including how user input is read by common
tools. For example, if you're using the CGI.pm module, you can use the hash
reference returned by the Vars() method or function as $defaults (but see
below for an easier way if you're using CGI.pm). You can also use the
hashes returned from other tools that parse form input, such as the
cgi-lib.pl library or the getcgivars() function. In the last two cases,
note that those functions return hashes instead of hash references, so you
should create a reference when calling defaultify():
%my_defaults= &getcgivars ; $new_HTML= &defaultify($HTML, \%my_defaults) ;
Of course, you can always create your own default set:
$new_HTML= &defaultify($HTML, { name => 'Coltrane',
citycb => [qw(SF LA NY)] } ) ;
or the same thing, using a different list format:
$new_HTML= &defaultify($HTML, { name => 'Coltrane',
citycb => "SF\0LA\0NY" } ) ;
As a special case, if you're using the CGI.pm module, you can give a
reference to a CGI object as $defaults, and defaultify() will use the
current parameters in the object as its default set. For example:
$q= new CGI ; $new_HTML= &defaultify($HTML, $q) ;
As another special case, if $defaults is undefined, then defaultify()
will clear all form fields; in other words, passing undef is the same
as passing an empty hash reference.
If defaultify() is called in list context, it returns two values: the
defaultified HTML as above, and a reference to a hash that contains all
the leftover defaults, i.e. those that were not set in any form field.
That hash is in the same format as the input defaults hash, and is a subset
of it (and any included lists are subsets of their respective lists). It's
useful if you need to know which values were set and which were not.
Also, passing that hash reference to hidden_vars() and inserting the result
into $new_HTML means that all data in the original defaults hash is now
represented in the form.
Besides defaultify(), this module provides other functions that some users
may find helpful. subhash() creates a subset of a hash and returns a hash
reference, suitable for use when calling defaultify(); this is useful to
set only certain fields in a form. hidden_vars() creates hidden
form fields that represent a given set of form data, such as the set of
unused defaults returned by defaultify(); hidden_var() creates one
well-formatted hidden form field. parse_tag() and build_tag() parse an
HTML tag into its tag name and attributes, and rebuild it. For details on
these functions, see the EXPORTS section below and the examples in the
synopsis above.
@EXPORT= qw( defaultify subhash ) ; @EXPORT_OK= qw( hidden_vars hidden_var parse_tag build_tag ) ;
The :parse symbol imports
parse_tag() and
build_tag().
The :all symbol imports everything in @EXPORT and @EXPORT_OK.
$HTML but with all form fields set to best
represent the values specified in the $defaults hash (which may include
clearing explicitly set fields). $HTML is presumed to be a block of
HTML with one or more form fields. If $form_name is given, then only
the form with that name in $HTML is affected. Otherwise, all form
fields in $HTML are set appropriately.
$defaults is a reference to a hash. The keys of that hash are form
field names, and the values are what those form fields should be set to.
Each value can be a scalar with one value, a scalar with multiple values
separated by the null character ``\0'', or an array reference. The last
two forms can be used to represent multiple values associated with the
same field name. $defaults may also be undefined, in which case it's
treated as an empty hash and clears all form fields of their default
values, even if some are set in the input HTML. As a special case,
$defaults can be a reference to a CGI object as created by the CGI.pm
module, and defaultify() will call its Vars() method to use the object's
current parameters as the set of defaults.
If called in a list context, defaultify() returns the defaultified HTML as
described above, and a reference to a hash of all the defaults in
$defaults that were not set anywhere in the HTML. That hash is in the
same format as $defaults, and is a subset of it.
For further explanation and examples, see the DESCRIPTION section above.
$hashref, containing only those
elements named in @keys. Returns a reference to the created hash. Any
elements named in @keys that do not exist in %$hashref will be created
in the result hash with an undefined value.
If you want the created hash itself instead of a reference to it, use
something like ``%{ &subhash(...) }''.
hidden_vars($data_set)hidden_vars(%data_set)<input type=hidden> tags that
represent the form data defined in $data_set. $data_set points to
a hash of form data that is in exactly the same format as the $defaults
parameter of the defaultify() function, and as the second return value
(unused defaults) from defaultify() when called in list context. That is,
the hash keys are field names, and each hash value can be any of a scalar, a
list reference, or a scalar with a ``\0''-delimited list. (However, note
that a CGI object is not supported here.) You may also pass a complete
hash instead of a reference to one.
For any hash value that is a list, each element in that list will result in one hidden form field in the return string.
If you call hidden_vars() with the hash of unused defaults returned from
defaultify(), and insert the result into the defaultified HTML, you get a
form containing all data represented in the original default set, even if
some of the fields did not exist in the form.
<input type=hidden> tag that represents
the given name-value pair. The name and value are properly escaped with
character entity references if needed.
parse_tag($tag)parse_tag() parses the first tag found in $tag. $tag may safely
contain leading or trailing text, or other tags, and parse_tag() will
ignore them all. Tags within comments are correctly ignored.
Attributes without an explicit value, such as the ``multiple'' in
``<select name=foo multiple>'', are treated as if their value
is the empty string. Technically, in those cases the value should be
treated as equal to the name, e.g. the above ``multiple'' is equivalent to
``multiple=multiple''. However, browsers seem to treat its value as the
empty string, so *sigh* this module does the same.
Attributes with a value of the empty string are added to the tag without an
explicit value, i.e. an ``=...'' part. See the note in the parse_tag()
section just above.
Note that if you use parse_tag() to parse a tag and build_tag() to rebuild it,
the resulting tag string may differ from the original in the order and
capitalization of the attributes, but the meaning is the same.
No other modules are required, but HTML::Entities is preferred, and used if available.
For a given set of defaults, there may be more than one way to defaultify a form to return those results, e.g. if several fields have the same name. This routine tries to generate a reasonable choice in those cases (one tactic is to populate <select> tags before the others), but it may not always be the intended choice.
The input HTML must be valid HTML, of course. This module makes a reasonable effort to support certain invalid but common HTML, but it makes no guarantee that all invalid HTML will be handled the same way that browsers do. If you get unexpected results, check that your input HTML is valid.
If parse_tag() is used to parse a tag and build_tag() is used to rebuild it,
then the order and capitalization of the attributes may not match the
original. This should not affect the meaning (ergo behavior) of any HTML,
but it may be confusing to a human reader.
If HTML::Entities is not available, then only the four most common entities
(&, <, >,
") are supported. This may cause
problems if your HTML uses other character entity references.
James Marshall (james@jmarshall.com)
Copyright (c) 1996, 1997, 2002, James Marshall. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl(1), HTML::Entities