NAME

SYNOPSIS

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

DESCRIPTION

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.

EXPORTS

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

defaultify($HTML, $defaults [, $form_name])

In scalar context, returns $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.

subhash($hashref, @keys)

Creates a subset of the hash pointed to by $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)

Returns a string consisting of "<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.

hidden_var($name, $value)

Returns a well-formatted "<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)

Parses an HTML tag into its tag name and attributes. Returns a two-element list of the tag name and a reference to a hash of attributes. The tag name may start with "/" for an end tag. In the attribute hash, the keys (attribute names) are lowercased, and the values have been resolved to remove character entity references where possible. The values do not contain their surrounding quotes.

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.

build_tag($tag_name, $attr)

build_tag($tag_name, %attr)

Builds an HTML tag string from the tag name and attribute hash, and returns it. Both parameters are in the same format as the return values from parse_tag(). The attribute hash can be passed as either a hash reference or a full hash. All attribute values are properly escaped with character entity references if needed.

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.

REQUIRES

BUGS

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 ("&amp;", "&lt;", "&gt;", "&quot;") are supported. This may cause problems if your HTML uses other character entity references.

AUTHOR

COPYRIGHT

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

SEE ALSO