MailForm v1.3
(c) Copyright 1997 Jonathan Potter
Left Side Software

This software requires Windows 95 or Windows NT 4.0 or later to run.

------------------------------------------------------------------------------
This program is distributed under the Shareware concept. If you like and use
this program, please consider registering to support the further development
of this and other great software. You will be given priority when asking for
technical support, and also receive notification of new releases of this and
other software.

Please see http://www.lss.com.au for information on registration.
------------------------------------------------------------------------------


1. Introduction

MailForm is an easy-to-use CGI program for Windows (Win32 only) that sends the results
of a submitted form as an email message. It is primarily designed for use with an
online registration form (and includes the ability to verify that a credit card is
a valid number), but can be used for any form. MailForm requires that there be a SMTP
mail server accessible from the web server machine.


2. Installing MailForm

Installing MailForm is simple provided you know your way around your web server;
the instructions given here are for Microsoft's Peer Web Services (IIS-jnr) and
assume you will be creating the form with Microsoft FrontPage, however the process
is very similar on other systems.

The MailForm executable (mailform.exe) must be copied into the cgi-bin directory
for your web server. In the default PWS setup, this directory is

	c:\INetPub\wwwroot\cgi-bin

The location may be different on your system, however. This is the only step needed
on the server side to install MailForm. If you are using FrontPage, it should
automatically notice a new addition to your cgi-bin directory (if not, just
Recalculate Links and it should appear in the tree on the left of the FrontPage
Explorer window).


3. Using MailForm

MailForm does not have a WebBot interface, so you can't configure it with a GUI
of its own. However, it is very easy to set up and can be configured through the
FrontPage interface.

Assuming you already have a form created, the first step is to assign MailForm as
the Handler for your form. To do this, right-click on the form and select 
Form Properties... to bring up the Form Properties dialog. Set the Handler type
to "Custom ISAPI, NSAPI, or CGI Script", and then click the Settings button.
The Settings for Custom Form Handler should be configured as follows:

	       Action:	http://www.company.com/cgi-bin/mailform.exe
	       Method:	POST
	Encoding type:

You must give the complete URL for the mailform.exe in the Action field. Click OK
when you have configured the Settings.


4. Configuring MailForm

Each form that uses MailForm can have its own configuration. MailForm is
controlled by the use of Hidden fields within the form. These are fields that
have a name and a value like any other, but are not displayed on the page.
In FrontPage, you add Hidden fields to a form in the Form Properties dialog.
Click Add to add each field, one at a time.

All MailForm configuration fields begin with an underscore character, a
number, and then another underscore (eg _1_). This identifies them as a MailForm
field, and the number is a code used to identify the particular type of field.

Currently there are four different type of MailForm fields:

	_1_	System field
	_2_	Ignore field
	_3_	Credit card number field
	_4_	Required field


The System fields are as follows:

	Name			 Value

	_1_MailTo		 The address to email the results to (eg fred@company.com)
	_1_MailServer		 The address of the SMTP mail server (eg mail.company.com)
	_1_MailFrom		 The address email is to "come from" (can be any valid address)
	_1_MailSubject		 The subject line of the email
	_1_SuccessDocument	 URL to return if the operation succeeds
	_1_FailureDocument	 URL to return if the operation fails
	_1_InvalidCardDocument	 URL to return for an invalid credit card number
	_1_RequiredFieldDocument URL to return if a required field is missing

The _1_MailTo address is the actual address the email will go to, and so must be valid.
Likewise, _1_MailServer is the address of the SMTP mail server and must also be valid.
_1_MailFrom and _1_MailSubject are not required, but you may like to set these for your
own convenience. If _1_MailFrom is set, it must be a valid address (contain exactly one
@ character).

The four documents, Success, Failure, InvalidCard and RequiredField are the URLs of
documents returned depending on the success or failure of the form submission.
do not work from within the cgi-bin directory (where the document will be served from).
If they are not supplied, a brief default message is given to the user.


The Ignore field (_2_) can be added to the name of any fields on the form, to cause
MailForm to ignore them. They will not be included in the email that is sent.
For example, you can give the Submit button the field name _2_Submit, to prevent
it being included in the email.


The Credit card number field (_3_) lets you verify that a credit card number
entered by the user is a valid card number (of course, it can only check that
the card number is valid, not that the card itself is valid!). If any field names
begin with _3_ MailForm will check to see whether the contents are a valid credit
card number. If not, the operation will fail and the _1_InvalidCardDocument file
will be served to the user.


Any fields marked as required (_4_) will cause the RequiredFieldDocument to be
returned to the user if the fields are not supplied.


5. The MailForm.INI file

MailForm v1.3 and greater now has the option of an external configuration file. This
file must be called mailform.ini, and placed either in the cgi-bin directory along with
the mailform.exe program, or the Windows or Windows System directory.

Currently the mailform.ini file consists of a single section, Settings, with two
optional parameters:

[Settings]
MailIntro=Submitted at %1 from %2
MailServer=mail.company.com

MailIntro allows you to change the introduction line of mail messages that MailForm
sends. Use %1, %2, etc, to insert information about the current message. The codes
available are:

	%1	Date & Time
	%2	Remote address
	%3	Remote user
	%4	HTTP agent (ie the user's Browser)

MailServer allows you to configure a global mail server for use with MailForm. If
the _1_MailServer line is not given in the form, the value supplied here will be
used as a default. You may want to use this if you don't want to make the address
of your mail server known publicly.


6. MailForm is Shareware

The unregistered version of MailForm is fully functional, however it does contain
a couple of reminders for you to register it. The first is a blurb at the bottom of
each email it sends for a completed form. The second is a brief message at the
bottom of the document served to the user for a successfully completed form.

If you register MailForm you will receive a program to unlock it and remove these
two messages. You will also be helping to support the author, and encourage the
development of more great software like this. See http://www.lss.com.au for more
information.


7. Release History

	v1.0     Aug 97	 - First public release

	v1.11 21 Aug 97  - _1_SuccessDocument, etc, can now handle URLs to
                           redirect to as well as document path names.

                         - A bug was fixed which would prevent email being
                           sent correctly if the mail server name given
                           contained more than three parts (eg xxx.yyy.com
                           would be ok, but www.xxx.yyy.com would fail)

	v1.2  26 Aug 97  - Closed off a potential security hole; the
                           _1_xxxDocument fields had the potential to be
                           used to return any file on your system if the
                           permissions of the HTTP server were set incorrectly
                           and someone used your copy of MailForm with their
                           own form. The _1_xxxDocument fields now only accept
                           a URL to the file to return - you will need to modify
                           your forms if you upgrade to 1.2.

                           Sorry for any inconvenience. If anyone specifically
                           needs the old behaviour of the document fields, please
                           contact me. 

			 - Added _4_ required fields, and the
                           _1_FieldRequiredDocument document to be served if a
                           required field is missing. Now only requests Windows
                           Sockets 1.1 instead of 2.0; should fix problems
                           people have had getting the email to work if they are
                           running a Windows 95 web server. 

	v1.3   4 Sep 97  - Added mailform.ini file support
