CSMailForm Readme
CoolServlets.com
Version 1.1
April 21, 1999

CSMailForm 1.1 is a Java servlet that takes input from HTML forms and sends an email with the given information. It uses the CSEmail package 1.1.

Features

Installation

This program requires a web server that has servlet support. Such web servers include Java Web Server by Sun, Netscape Enterprise Server, and versions of Apache. If you are not sure if your web server has servlet support, contact your System Administrator. Various external servlet engines are also available. The servlet has been tested specifically with JRun.

Step 1: Copying Files

A few files must be copied to the correct locations in order to make the servlet run.

If you are not familiar with your Web Server servlet environment, it is recommended that you copy the CSInstallation.class file into your servlet directory for specific directory instructions. If you are familiar with your servlet environment, you can skip to the next paragraph. Your servlet directory is often named servlets underneath your main Web Server directory. For example, on a Windows machine with Java Web Server, the servlet directory is: c:/JavaWebServer1.1.3/servlets/ . Once you have copied CSInstallation.class into the appropriate folder, you should run the servlet by calling it from a web browser:

The script will then give you detailed information about where to copy files.

You are now ready to begin copying files. First, the class files: In the dist folder of this distribution you'll find the files CSMailForm.class, CSMailForm.jar and a folder called com (with the subdirectory named coolservlets which holds more .class files). You should copy the CSMailForm.class file into your servlets directory. You then have a choice of copying the com folder into your servlets directory or copying the CSMailForm.jar file into a folder that is in the classpath of your servlet environment (often a folder named lib). Using the jar can make your servlet run faster. However, if you do use it, you'll most likely have to shut down and restart your web server to make the servlet engine recognize the new file.

Next, you'll need to copy the config folder (in the root directory of this distribution) to where your servlet engine defaults to reading files. If you don't know where this is, remember that you can use the CSInstallation.class servlet to find out. In Netscape Enterprise Server, this folder is called config. On the Java Web Server, it is the main server directory such as: c:/JavaWebServer1.1.3/ . If you have installed a CoolServlets.com servlet in the past, you can simply copy the contents of the coolservlets/config into your existing directory.

Step 2: Editing the Configuration Files

You'll need to edit some settings to make the servlet fully functional.

Traverse to the coolservlets/config folder that you copied into your servlet environment and use a text editor to change the MailFormProperties file. Instructions for changing the settings are contained in that file.

After that the servlet is ready to go!

Usage

You should see the html pages in the demo directory as a guide for implementing you own forms. One way to test everything would be to simply copy the demo documents onto your web server and then use them.

To reload the properties, type in the following URL:

http://www.yourSite.com/yourServletPath/CSMailForm?properties=reload
This feature is turned off by default. To turn it back on, change the field in your properties file: "displayProperties=no" to "displayProperties=yes". I would recommend you use this feature only if you need to. You should keep it turned off for most of the time.

Every field is explained below:

There are quite a few options available when setting up this servlet, so I'm going to show what each of the parameters do. You should refer to this page when setting up your CSMailForms!

The form header should look like this:
<form name="CSMailForm" 
      action="http://yourHost.com/yourServletDir/CSMailForm" 
      method=post>

All of the following fields can be either "hidden" or "text" (it depends what you want to do with this servlet).

To specify the TO field of an email, you have 2 options.
The first, is to specify an email address and/or a name. So if I want to send an email to Bill Lynch at bill@coolservlets.com, I would do this:

<input name="toName" type="hidden" value="Bill Lynch">
<input name="toEmail" type="hidden" value="bill@coolservlets.com">

The other option (if you would like to specify multiple people to send this email to) is to use one to field like so:
<input name="to" type="hidden" value="Bill,bill@coolservlets.com,Matt,matt@coolservlets.com">

Notice that the value of the field is a comma delimited list of names and email addresses. This allows you to send multiple "TO" recipient.
The FROM fields work much the same way (although you obviously can't have multiple FROM fields):
<input name="fromName" type="hidden" value="Some One">
<input name="fromEmail" type="hidden" value="person@place.com">

The CC and the BCC fields work much like specifying multiple TO addresses:
<input name="cc" size=60 type="hidden" value="Person,person@place.com">
<input name="bcc" size=60 type="hidden" value="Dude,dude@place.com">
or for instance, multiple CC's:
<input name="cc" size=60 type="hidden" value="person@place.com,dude@place.com,entity@place.com">

You can specify required fields that the users MUST fill in (or else the email won't be sent):
 
<input name="required" type="hidden" value="">

You can also choose an error message that is served up in the event that the forms are not properly filled out.
<input name="reqError" size=60 type="text" value="Oops! The following fields are required:">

To timestamp the email message:
<input name="timestamp" type="hidden" value="yes">

To redirect the users to another page, use the "redirect" field.
<input name="redirect" type="hidden" value="http://www.cnn.com">

To redirect the user to another page in the event of an error, use the "onErrorPage" field:
<input name="onErrorPage" type="hidden" value="http://www.yourSite.com/errorpage.html">

The all important subject and message fields:
<input name="subject" size=60 type="text" value="The Subject">
<textarea rows=5 cols=50 name="message" size=60 type="text">Your message goes here.</textarea>

The following parameters pertain to the response page that the user will see once an email has been submitted.
<input name="response" size=60 type="text"   value="Thank you for your feedback! We look forward to your comments.">
<input name="title" size=60 type="text"      value="My Company - Thank you!">
<input name="fontFace" size=20 type="text"   value="arial,helvetica">
<input name="fontSize" size=20 type="text"   value="3">
<input name="linkBack" size=20 type="text"   value="http://www.cnn.com">
<input name="textBack" size=20 text="text"   value="Go Back">
<input name="background" size=20 type="text" value="dog.gif">
<input name="bgcolor" size=20 type="text"    value="#ffffff">
<input name="text" size=20 type="text"       value="#000000">
<input name="link" size=20 type="text"       value="#0000ff">
<input name="vlink" size=20 type="text"      value="#800080">
<input name="alink" size=20 type="text"      value="#ff0000">

Finally, to send the email, use this:

<input type="submit" value="Send Email">

One Additional Note:
If you do not use a field (ie, if you decide you don't need to include the "redirect" field) the best thing to do is to leave it out entirely (instead of doing this: value="").

Problems?

We have made every effort to make this servlet easy to install and as robust as possible. If you are having problems making it work, first go back over the installation instructions and make sure you followed them exactly. If that does not fix the problem, verify that servlets are working correctly on your web server. Additional help can be found on http://www.coolservlets.com where FAQ's or discussion forums may exist for this servlet.

Bugs in the servlet can be reported to bugs@coolservlets.com. You may also send descriptions of any other problems you are having with the servlet to that address, but we cannot guarantee a reply due to our busy schedules.

If you require technical support, please see below for information about how to purchase it.

Source

The full source of the servlet be found in the src. folder in this distribution. If you would like compile it, you'll need the Servlet SDK which is available on the Java website: http://java.sun.com .

Technical Support

Individuals or companies that would like technical support for this servlet can buy unlimited email tech support for $50. A support contract can also be purchased for $150 which provides unlimited email tech support for all CoolServlets.com servlets. Please see http://www.coolservlets.com/support for further details.

Purchasing technical support guarantees a quick resolution to any problems you have with CoolServlets.com servlets. It is also a great way to aid the continued development of further high quality, free, open-source servlets.

License

This servlet is distributed under the GNU Public License. This means that the program is completely free (see below for legalese).

However, there are a few voluntary things that we would really appreciate: provide links back to CoolServlets.com instead of redistributing the code (this will guarantee that people will always be able to get the latest version), and send us bug reports or feature requests. Also, we encourage you to put the CoolServlets.com button somewhere on your site so that other people can find out about our free servlets. Please spread the word about CoolServlets.com!

     Copyright (C) 1999  Matt Tucker and Bill Lynch
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
 
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA