NAME

CGI::ContactForm - Generate a web contact form

SYNOPSIS

    use CGI::ContactForm;

    contactform (
        recname         => 'John Smith',
        recmail         => 'john.smith@example.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.

By default the sender gets a bcc copy. If the email address stated by the sender is invalid, by default 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... However, by setting the nocopy argument you can prevent the sender copy from being sent.

Arguments

CGI::ContactForm takes the following arguments:

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

    Optional
    --------
    smtp                'localhost'
    styleurl            (none)
    returnlinktext      'Main Page'
    returnlinkurl       '/'
    subject             (none)
    nocopy              0
    bouncetosender      0
    formtmplpath        (none)
    resulttmplpath      (none)
    maxsize             100 (KiB)
    maxperhour          5 (messages per hour per host)
    tempdir             (none)
    spamfilter          '(?is:</a>|\[/url]|https?:/(?:.+https?:/){3})' (Perl regex)

    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.'
    sent_to_short       'The message was sent to %s.'
    encoding            'ISO-8859-1'

Customization

There are only two compulsory arguments. The example CGI script contact.pl, that is included in the distribution, also uses 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.

If the default value localhost isn't sufficient to identify the local SMTP server, you may need to explicitly state its host name or IP address via the smtp argument.

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.

Spam prevention

Behind the scenes CGI::ContactForm performs a few checks aiming to complicate and/or discourage abuse in the form of submitted spam messages.

• The number of messages that can be sent from the same host is restricted. The default is 5 messages per hour.

• A customizable spamfilter is applied to the body of the message. By default it allows max 3 URLs that start with http:// or https://, and it rejects submissions with </a> or [/url] in the message body.

• When sending a message, the request must include a cookie.

The thought is that normal use, i.e. establishing contact with somebody, should typically not be affected by those checks.

INSTALLATION

Installation with Makefile.PL

Type the following:

    perl Makefile.PL
    make
    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.

• Create the directory /www/username/cgi-bin/lib/CGI/ContactForm, and upload MHonArc.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 the non-standard modules CGI.pm and Mail::Sender.

AUTHENTICATION

If you have access to a mail server that is configured to automatically accept sending messages from a CGI script to any address, you don't need to worry about authentication. Otherwise you need to somehow authenticate to the server, for instance by adding something like this right after the use CGI::ContactForm; line in contact.pl:

    %Mail::Sender::default = (
        auth      => 'LOGIN',
        authid    => 'username',
        authpwd   => 'password',
    );

auth is the SMTP authentication protocol. Common protocols are LOGIN and PLAIN. You may need help from the mail server's administrator to find out which protocol and username/password pair to use.

If there are multiple forms, a more convenient way to deal with a need for authentication may be to make use of the Sender.config file that is included in the distribution. You just edit it and upload it to the same directory as the one where Sender.pm is located.

See the Mail::Sender documentation for further guidance.

AUTHOR, COPYRIGHT AND LICENSE

  Copyright (c) 2003-2019 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.

SEE ALSO

CGI::ContactForm::MHonArc, Mail::Sender

cpanm CGI::ContactForm

perl -MCPAN -e shell
install CGI::ContactForm