NAME

HTML::FormHighlight - Highlights fields in an HTML form.

SYNOPSIS

    use HTML::FormHighlight;

    my $h = new HTML::FormHighlight;
    
    print $h->highlight(
        scalarref => \$form,
        fields    => [ 'A', 'B', 'C' ],
    );
    
    print $h->highlight(
        scalarref    => \$form,
        fields       => [ 'A', 'B', 'C' ],
        highlight    => '*',
        mark         => '<!-- HIGHLIGHT HERE -->',
        all_in_group => 1,
    );

DESCRIPTION

HTML::FormHighlight can be used to highlight fields in an HTML form. It uses HTML::Parser to parse the HTML form, and then places text somewhere before each field to highlight the field. You can specify which fields to highlight, and optionally supply a CGI object for it to check whether or not an input value exists before highlighting the field.

It can be used when displaying forms where a user hasn't filled out a required field. The indicator can make it easier for a user to locate the fields that they've missed. If you're interested in more advanced form validation, see HTML::FormValidator. HTML::FillInForm can also be used to fill form fields with values that have already been submitted.

METHODS

new()

    Create a new HTML::FormHighlight object.  Example:
    
        $h = new HTML::FormHighlight;

highlight()

Parse through the HTML form and highlight fields. The method returns a scalar containing the parsed form. Here are a few examples:

    To highlight the fields 'A', 'B' and 'C' (form on disk):
    
        $h->highlight(
            file   => 'form.html',
            fields => [ 'A', 'B', 'C' ],
        );
 
    To highlight the fields 'A' and 'B' with a smiley face
    (form as a scalar):
    
        $h->highlight(
            scalarref => \$form,
            fields    => [ 'A', 'B' ],
            highlight => '<img src="smiley.jpg">',
        );       
    
    To highlight the fields 'A' and 'B' if they haven't been supplied
    by form input (form as an array of lines):
    
        $q = new CGI;
        
        $h->highlight( 
            arrayref => \@form,
            fields  => [ 'A', 'B' ],
            fobject => $q,
        );

Note: highlight() will only highlight the first option in a radio or select group unless the all_in_group flag is set to a true value.

Here's a list of possible parameters for highlight() and their descriptions:

• scalarref - a reference to a scalar that contains the text of the form.
• arrayref - a reference to an array of lines that contain the text of the form.
• file - a scalar that contains the file name where the form is kept.
• fields - a reference to an array that lists the fields to be highlighted. If used in conjunction with "fobject" or "fdat", only the fields listed that are empty will be highlighted.
• highlight - a scalar that contains the highlight indicator. Defaults to a red asterisk (<font color="#FF0000" size="+1"><b>*</b></font>).
• mark - a regex specifying where to place the highlight indicator. If this is empty, the indicator will be inserted directly before the form field. The HTML form does not need to contain the text specified in the regex before each form field. highlight() will only use a mark for a field if there is no other form field before the field it's highlighting. If there is more than one mark before a field, it will only highlight the last mark. If it doesn't find a mark, it will insert the indicator directly before the form field. Here are a few examples:

      code:
      =====
      
      $h->highlight(
          file      => 'form.html',
          fields    => [ 'A', 'B', 'C' ],
          mark      => '<!-- MARK THIS -->'
          highlight => '***',
      );
      
      
      input:
      ======
      
      <input type=text name="A">
      <!-- MARK THIS --> Field B:<input type=text name="B">
      <input type=text name="C">
      
      output:
      =======
      
      ***<input type=text name="A">
      <!-- MARK THIS -->*** Field B:<input type=text name="B">
      ***<input type=text name="C">    
      
      
      input:
      ======
      
      Field A: <!-- MARK THIS --><br><input type=text name="A">
      Field B: <input type=text name="B">
      Field C:
          <!-- MARK THIS --><input type=radio name="D" value="1">
          <input type=text name="C">
          <input type=radio name="D" value="2">
          
      output:
      =======
      
      Field A: <!-- MARK THIS -->***<br><input type=text name="A">
      Field B: ***<input type=text name="B">
      Field C:
          <!-- MARK THIS --><input type=radio name="D" value="1">
          ***<input type=text name="C">
          <input type=radio name="D" value="2">    
          
          
      input:
      ======
      
      Field A:
          <!-- MARK THIS --><br> Foo...
          <!-- MARK THIS --><br> Bar...
          <input type=text name="A">
          
      Field B:
          <!-- MARK THIS --><input type=hidden name="E"><input type=text name="B">
          
      Field C:
          <select>
          <option>
          <input type=text name="C">
          </select>
          
      output:
      =======
      
      Field A:
          <!-- MARK THIS --><br> Foo...
          <!-- MARK THIS -->***<br> Bar...
          <input type=text name="A">
          
      Field B:
          <!-- MARK THIS --><input type=hidden name="E">***<input type=text name="B">
          
      Field C:
          <select>
          <!-- MARK THIS --><option>
          ***<input type=text name="C">
          </select>

  Warning: Since the mark field is a regular expression, make sure to escape it appropriately. "\s" will insert the highlight after the last space character. To replace all occurrences of a backslash followed by the letter s, use "\\\s".

• all_in_group - set this to 1 if you want all options in a radio or checkbox group to be highlighted. It's set to 0 by default.
• fobject - a CGI.pm object, or another object which has a param() method that works like CGI.pm's. HTML::FormHighlight will check to see if a parameter does not have a value before highlighting the field.
• fdat - a hash reference, with the field names as keys. HTML::FormHighlight will check to see if a parameter does not have a value before highlighting the field.

BUGS

• highlight() will add the highlight indicator inside an HTML tag if you're not careful.

  For example, if you use "\s" as your mark and "***" as your indicator,

      A: <font face="arial"><input type=text name="A">
      
    will result in:
    
      A: <font ***face="arial"><input type=text name="A">
      
    not:
    
      A: ***<font face="arial"><input type=text name="A">

VERSION

0.03

AUTHOR

Adekunle Olonoh, ade@bottledsoftware.com

CREDITS

Hiroki Chalfant

COPYRIGHT

Copyright (c) 2000 Adekunle Olonoh. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

HTML::Parser, CGI, HTML::FormValidator, HTML::FillInForm