Quick Links

LATTE (course materials)

Library OneSearch (library collections)

Brandeis Scholar (research databases)

eJournals A-Z (online journals)

Research Guides (subject guides)

Account Tools (passwords & more)

Get Help! (technology and library)

Facebook     Twitter     WordPress     Flickr

Soupermail Form Tutorial


Summary

If you are building a web form for the Brandeis website, you can use the Soupermail script to email and process the results. Soupermail is a flexible and powerful script installed on the webserver to handle all email form processing. This document explains how to setup your form to use Soupermail in a basic capacity.

Documents you'll need

•    An HTML page containing the form
•    A configuration text file
•    Optional: An HTML success page for submitting the form
•    Optional: A configuration file for how the form is received
•    Optional: A configuration file for how the form is returned to the person filling the form out
•    Optional: An HTML failure page in case the user fills something out incorrectly

Form Setup

To create a form you can use a WYSIWYG editor (Such as GoLive or Dreamweaver) or you can manually code the HTML.  Sometimes it is easier to use both.

For making the form you will use the <form> tag to define where the form code starts and ends, and the <input> tags to provide fields or various elements of the form that the user fills out.  The form will be coded similar to the following:

forms.html

 <html>
<body>
<form action="/cgi-bin/soupermail.pl" method="POST" name="form_name">
<input type="hidden" name="SoupermailConf" value="configure.txt">
<p>Enter your name here: <input type="text" name="Name"></p>
<p>Enter your email here: <input type=”text” name=”Email”></p>
<p>Choose Yes or No:<br>
Yes: <input type=”radio” name=”Decision” value=”Yes”><br>
No: <input type=”radio” name=”Decision” value=”No”>
<input type=”submit” name=”Submit” value=”Submit Button”>
</form>
</body>
</html>


As you can see there is an opening and closing tag for the HTML code, the body of the page, the form, and paragraphs inside of the form.  The inputs only need one tag because they are treated more as individual objects than tags that define an area.  The tags have variables (such as name or type) which can be set to various options depending on what you want.

Inside the HTML of the form on the page, there will be the following code:

<form action="/cgi-bin/soupermail.pl" method="POST" name="form_name">


The bolded part is important so that the form knows where the soupermail script is.

One other requirement is to set a hidden form field telling Soupermail the name of and where to find your configuration file:

<input type="hidden" name="SoupermailConf" value="configure.txt">


For this example, we're expecting that the configure file is called configure.txt and is located in the same directory as the HTML form itself. You can use subdirectories; you simply need to include the path in the value. For example, if you have a folder called application_form, the proper code would be: value="application_form/configure.txt"

Inputs

There are a few options for inputs when you are creating your form.  First let’s examine the anatomy of the input code:
<input type=”type_of_input” size=”40” name=”field_name” value=”value_of_input”>


The type of input can be any of the following:
•    text
•    radio
•    checkbox
•    and a submit

The field name is what the form refers to that specific input by.  This can later be used in referencing the value the user submitted.

The value depends on what type of input you are dealing with.  
•    If you are using a text input, this is the default text that will be in the field.
•    If you are using a radio button, this is what the value of that radio button will return.  The name of the radio buttons in one question should all be the same. (i.e. <input type=”radio” name=”question” value=”yes”> <input type=”radio” name=”question” value=”no”>
•    If you are using a checkbox, this is the same as a radio button.
•    If you are using a submit button, the value can be whatever you want the button to say, such as “Submit Answers”.

 
There are also drop down menu options which are implemented like so:
<form>
<select name="cars">
<option value="volvo">Volvo</option>
<option value="saab">Saab</option>
<option value="fiat">Fiat</option>
<option value="audi">Audi</option>
</select>
</form>

The Configuration File (Basic Setup)

The configuration file tells Soupermail how to handle your form - who to send it to, and what to do with the data. At its simplest, your configuration file should include two things: the collection address, and the subject you want for the email.

configure.txt
#this is who gets the email
mailto: yourname_here@brandeis.edu
#This is the email subject
subject: Question from the GSAS webpage



Note that you can have comments to the lines in your configuration file (any line starting with a pound sign ‘#’).

There are more things that can be added to the configuration file but we’ll cover that later.

Keeping your configuration file secret


Since the configuration file is a text file, it can be read by pointing a browser towards it. If this displeases you, you can try this trick: simply name the file with a .con extension instead of .txt. The webserver has been instructed to not serve up files ending in .con. [note: be sure your hidden form field correctly refers to the configuration file with the proper extension, so it would read value=“configure.con”].

The Configuration File (Advanced Setup)


The above example simply returns the form fields in the order in which they were listed on the form. You can, however, arrange and format the data in any way you wish. This requires a bit more work (and several more formatting files), but the results may be more visually appealing.

To start, you'll need a new file for each different format you'd like. Soupermail allows you to have one format for the collecting address, and one format for the person filling out the format (a thank you message, or a confirmation message). Thus, you may have the following files:

•    form.html    - Your main form
•    configure.txt    - The configure file
•    collection-format.txt    - Mail template
•    response-format.txt    - Sender template
•    success.html    - Success page
•    failure.html    - Failure page

[Note that the files can be named anything you want, this is just an example]

You can also create required fields that the user has to fill out, otherwise the form will return an error (or go the to failure page you designate).  This uses a logic algorithm method.  For example, the following code would make it so that both field_name and field_name2 have to be filled out for the form to input correctly: required: (field_name && field_name2)

 
You'll need to change your config file to reference the other files. Here's the format you'll now need:

configure.txt
#Required Fields for the user to have
required : (name && Email)
#This sets the format for the email coming to you
mailtemplate: collection-format.txt
#This sets the format for the email sent to the person filling out the form
sendertemplate: response-format.txt
#page user gets to on successfully filling out form
success: success.html
#page user gets to when not filling out the form correctly
failure: failure.html
#this is who gets the email
mailto: yourname_here@brandeis.edu
#This is the email subject
subject: Question from the GSAS webpage



Example files for each of the format documents are available:

 
collection-format.txt
This information was collected from your form on <output name="http_date"> at <output name="http_time">.
Name: <output name="name">
email: <output name="Email">
organization: <output name="Organization">
They found out about you from:
<output name="learned_about">


response-format.txt
Thank you, <output name="name">, for filling out our form online.  You provided the following information on <output name="http_date"> at <output name="http_time">.
---------------------------------------------------------
Name: <output name="name">
email: <output name="Email">
organization: <output name="Organization">
They found out about you from:
<output name="learned_about">


Essentially you can send back any variable in the email as long as you refer to its field name in the format <output name="field name">
Custom Response Page

Be aware that you'll have to reference all links and image files with their absolute locations (not relative URLs). This is because the Soupermail submittal process lives in another location on the server, and once you fill out the form, you'll be at a different URL than your website. If you want users to return to your site, make sure you use full URLs in your links (such as http://www.brandeis.edu/webservices/ instead of index.html)

Avoiding Spam


Normally the Brandeis servers are set up to prevent spam bots from using the forms on the server.  But occasionally they might find a way to submit items using your form.  There are two things you can do to absolutely prevent this from happening.  The first, as stated above, is to make sure your configuration file ends with “.con” instead of “.txt”.  This will prevent spam bots from reading your configuration file.

The second thing you can do is create something called a “Captcha,” which basically is a small field you put in a form with a question only a human user can answer correctly.  You might have seen this on some sites where you have to sign up to a service and then re-write some weird looking text into a form field before submitting.  One style of Captcha is to ask a question such as “What is the name of this University?” or “What is the president of this university’s name?”  Here is how you would implement that.

First in your form HTML you will need the following code:
<p>To prevent spam robots from submitting this form, please enter in the name of this University to prove you are human:
<input name="captcha" type="text"></p>


Then you will need to add to your configure file the following:
if: !(captcha eq 'Brandeis University' || captcha eq 'Brandeis') then error: true


In this code, there is an if statement which says if the captcha field does not (!) equal (eq) “Brandeis University” or (||) “Brandeis” then return an error when the user tries to submit.
You can try to copy the code and modify it yourself for your own question, or you can use the one I have provided.

Learning More


Soupermail is quite powerful. It pays to learn more. You may want to refer to the online manual:
http://soupermail.sourceforge.net/manual.html

The project is at Sourceforge:
http://sourceforge.net/projects/soupermail/

Document version 2.0
David Wisniewski & Ben Douglas
January 31, 2008