NAME
    CGI::ContactForm - Perl extension for generating a web contact form

SYNOPSIS
        use CGI::ContactForm;

        contactform (
            recname        => 'John Smith',
            recmail        => 'john.smith@domain.com',
            smtp           => 'smtp.domain.com',
            styleurl       => '/style/ContactForm.css',
        );

DESCRIPTION
    This module generates a contact form for the web when the routine
    "contactform()" is called from a CGI script. Arguments are passed to the
    module as a list of key/value pairs.

    "CGI::ContactForm" sends a well formated (plain text format=flowed in
    accordance with RFC 2646) email message, with the sender's address in
    the "From:" header, and the sender gets a "bcc" copy. If the email
    address stated by the sender is invalid, the failure message is sent to
    the recipient address, through which you know that you don't need to
    bother with a reply, at least not to that address...

  Arguments
    "CGI::ContactForm" takes the following arguments:

                            Default value
                            =============
        Compulsory
        ----------
        recname             (none)
        recmail             (none)
        smtp                (none)

        Optional
        --------
        styleurl            (none)
        returnlinktext      'Main Page'
        returnlinkurl       '/'
        formtmplpath        (none)
        resulttmplpath      (none)
        maxsize             100 (KiB)

        Additional arguments, intended for forms at non-English sites
        -------------------------------------------------------------
        title               'Send email to'
        namelabel           'Your name:'
        emaillabel          'Your email:'
        subjectlabel        'Subject:'
        msglabel            'Message:'
        reset               'Reset'
        send                'Send'
        erroralert          'Fields with %s need to be filled or corrected.'
        marked              'marked labels'
        thanks              'Thanks for your message!'
        sent_to             'The message was sent to %s with a copy to %s.'
        encoding            'iso-8859-1'

  Customization
    There are only three compulsory arguments. The example CGI script
    "contact.pl", that is included in the distribution, also sets the
    "styleurl" argument, assuming the use of the enclosed style sheet
    "ContactForm.css". That results in a decently styled form with a minimum
    of effort.

    As you can see from the list over available arguments, all the text
    strings can be changed, and as regards the presentation, you can of
    course edit the style sheet to your liking.

    If you want to modify the HTML markup, you can have "CGI::ContactForm"
    make use of one or two templates. The enclosed example templates
    "ContactForm_form.tmpl" and "ContactForm_result.tmpl" can be activated
    via the "formtmplpath" respective "resulttmplpath" arguments, and used
    as a starting point for a customized markup.

INSTALLATION
  Installation with Makefile.PL
    Type the following:

        perl Makefile.PL
        make
        make test
        make install

  Manual Installation
    *   Download the distribution file and extract the contents.

    *   Designate a directory as your local library for Perl modules, for
        instance

            /www/username/cgi-bin/lib

    *   Create the directory "/www/username/cgi-bin/lib/CGI", and upload
        "ContactForm.pm" to that directory.

    *   In the CGI scripts that use this module, include a line that tells
        Perl to look for modules also in your local library, such as

            use lib '/www/username/cgi-bin/lib';

  Other Installation Matters
    If you have previous experience from installing CGI scripts, making
    "contact.pl" (or whichever name you choose) work should be easy.
    Otherwise, this is a very short lesson:

    1.  Upload the CGI file in ASCII transfer mode to your "cgi-bin".

    2.  Set the file permission 755 (chmod 755).

    If that doesn't do it, there are many CGI tutorials for beginners
    available on the web. This is one example:

        http://my.execpc.com/~keithp/bdlogcgi.htm

    On some servers, the CGI file must be located in the "cgi-bin" directory
    (or in a "cgi-bin" subdirectory). At the same time it's worth noting,
    that the style sheet typically needs to be located somewhere outside the
    "cgi-bin".

DEPENDENCIES
    "CGI::ContactForm" requires these modules:

        Mail::Sender
        Text::Flowed

    (can be downloaded from CPAN http://www.cpan.org/ )

    It also requires direct access to an SMTP server.

    If "Mail::Sender" and "Text::Flowed" need to be installed manually, you
    shall create "/www/username/cgi-bin/lib/Mail" and
    "/www/username/cgi-bin/lib/Text" and upload "Sender.pm" respective
    "Flowed.pm" to those directories.

VERSION HISTORY
    v1.15 (Aug 24, 2003)
        Referer check removed, since it made the script fail with certain
        browsers while its security value was limited.

    v1.14 (Jul 10, 2003)
        Handling of error messages improved.

    v1.13 (Jul 1, 2003)
        Code cleanup.

    v1.12 (Apr 11, 2003)
        References to the form data for saving memory.

    v1.11 (Apr 6, 2003)
        Markup for 'erroralert' modified for greater flexibility when
        editing the form template.

        Preparations for mod_perl.

    v1.10 (Apr 4, 2003)
        Template based customization added as an option.

    v1.03 (Mar 30, 2003)
        CGI.pm used for parsing form data.

        New argument: 'maxsize' - for limiting the message size.

    v1.02 (Feb 16, 2003)
        DOCTYPE declaration changed to XHTML 1.1.

    v1.01 (Feb 13, 2003)
        CSS validation error corrected.

    v1.0 (Feb 12, 2003)
        Additional arguments added that makes it possible to have the form
        display non-English text.

        Warnings enabled.

    v0.4 (Feb 9, 2003)
        Error alert message added. Also "ContactForm.css" was modified for
        this reason.

        Simple test script included in the distribution.

    v0.3 (Feb 7, 2003)
        Check of email syntax modified (hopefully now closer to RFC 822).

        Better structured code.

    v0.2 (Feb 5, 2003)
        Referer check in order to only accept data input from the generated
        form.

        Improved email validation.

    v0.1 (Feb 3, 2003)
        Initial release.

LATEST VERSION
    The latest version of "CGI::ContactForm" is available at:

      http://search.cpan.org/author/GUNNAR/

      http://www.gunnar.cc/contactform/

AUTHOR, COPYRIGHT AND LICENSE
      Copyright © 2003 Gunnar Hjalmarsson
      http://www.gunnar.cc/cgi-bin/contact.pl

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

