NAME
    Data::FormValidator::Util::HTML - HTML utility functions for DFV

SYNOPSIS
      # Add error tokens to an HTML page, for later 
      # use with Data::FormValidator and a templating system

      # Example #1, a standard Unix filter
      # takes input from STDIN and prints to STDOUT

      #!/usr/bin/perl 
      use Data::FormValidator::Util::HTML;
      print add_error_tokens();     

      # Example #2, modifying some HTML
      # you have as a scalar

      my $html = add_error_tokens(
            html=>\$html,
            prefix=>'err_',
      );

    The "add_error_tokens()" routine will add HTML::Template tags next to
    all the appropriate form fields, which can be used to display errors.

    Example HTML:

     <input type="text" name="fruit">

    Becomes:

     <input type="text" name="fruit"> <!-- tmpl_var name="err_fruit" -->

DESCRIPTION
    This module adds tokens to HTML pages, which can be used to display
    error messages generated by the Data::FormValidator module.

    The easiest way to understand this might be to check out the tutorial,
    which provides example of using the kind of output this module produces,
    including a screenshot.

    http://mark.stosberg.com/dfv/

add_error_tokens()
    This functions adds error tokens to some HTML and returns the modified
    HTML.

    input parameters:

    html (default: STDIN)
        This is the HTML to modify. It can be a file name, a file handle
        object, or the complete document to be parsed.

        If the argument is a plain scalar, then it is taken as the name of a
        file to be opened and parsed. If the file can't be opened for
        reading, then the constructor will return an undefined value and $!
        will tell you why it failed.

        If the argument is a reference to a plain scalar, then this scalar
        is taken to be the literal document to parse. The value of this
        scalar should not be changed before all tokens have been extracted.

        Otherwise the argument is taken to be some object that the
        "HTML::TokeParser" can read() from when it needs more data. Typi-
        cally it will be a filehandle of some kind. The stream will be
        read() until EOF, but not closed.

    prefix (default: 'err_' )
        This is the same 'prefix' that you define in your DFV profile to
        denote that these are error fields. I like to use "err_", so that's
        what the default is. :)

    style (default: 'ht_comment')
        Recognizing that people will want to use this different templating
        systems, you can set "style" to a pre-defined template style to use.
        Currently just a couple for HTML::Template are included, but patches
        are welcome for more.

        Here's what they look like:

         ht_comment: <!-- tmpl_var name="err_field" -->
         ht_tag      <tmpl_var name="err_field">

    prepend and append
        If you don't want to use one of the built-in styles or patch the
        code, fear not. "prepend" and "append" are for you. Use these to
        define what text you want to come before and after the field name.
        Defining these will override any setting for 'style'.

EXPORT
    "add_error_tokens()"

KNOWN ISSUES
    o   There is no way to specify which kinds of form fields get tokens
        added, or exactly where the tokens appear in relation to the field.

    o   The token adding is currently not related to a Data::FormValidator
        profile. It could potentially be even smarter by only adding tokens
        for fields that have the possibility of being missing or invalid in
        a profile.

SEE ALSO
    Data::FormValidator

AUTHOR
    Mark Stosberg, <mark@summersault.com>

COPYRIGHT AND LICENSE
    Copyright 2003 by Mark Stosberg

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