Please note: This document is not intended to teach you how to create HTML forms, but rather it assumes you already know how. There is documentation on the CWIS for creating HTML forms using Claris Homepage.
Here is the implementation design:
User requests an HTML document containing your form from our CWIS.
They enter whatever data is necessary to complete the form.
They press the Submit button you've provided on your form.
Their browser sends the data back to our CWIS.
Our CWIS runs the program name you specified in your form, passing the user data to the program as input.
The program name you specified will be the Perl script I wrote. This is where the meat of the process resides:
Crunches the input data into an usable format.
Reads the specified template file you created (see Step 2, below), and plugs in data where required.
If there are no errors, it will e-mail the filled-in template to whomever you told it to mail it to in your form (see Step 1, below).
A quick HTML document is sent to the user's browser saying the operation was a success.
If there are errors, a different HTML document is sent to the user's browser describing the error.
By design, this Perl script will serve most everyone's purpose for e-mailing the contents of any fill-out form.
You need to create two files on the CWIS machine using a login account. If you do not have one, please contact our Webmaster.
Step 1: Create a form.
Write your HTML document with the fill-out form in it. After you are done, add the following two fields inside the form:
Where filename should be the full pathname of a text file template which resides on the CWIS machine itself (for example, "/usr/users/foo/bar.txt") - *not* a URL! Each address is an e-mail address of a recipient. Use spaces to seperate addresses if multiple recipients are specified. You may have forms sent to FirstClass conferences, but you must make special arragements with the Digital Technologies group.
It is also a good idea to specify a subject for this piece of mail. To do this include a field name called _SUBJECT either as a hidden field, or something the user can specify (depending on your application). Please be sure to see the special note in Step 2 regarding subject lines. Here are some examples:
To make a field required, use a field name which begins with an underscore. For example:
The user will be informed if a required field is missing, but won't be told which one. It is good practice to denote required fields on your form.
Do NOT name any of your fields "email". You already have a hidden field named email, and having the duplicate fields will interfere with the form functionality, sometimes without giving you an error message.
If you would like a different screen other than the default Done! screen, specify a DONESCREEN variable with the complete URL (do not use a relative path!) you want to return to as the value. For example:
Step 2: Create the text template file.
This file should contain a template of how you want the e-mail to look. Where there is data to be filled in, put a %%XX, where XX corresponds to a field NAME from the form you created. For instance, if my HTML form defined this:
Then a line in my template file would be something like:
Your name: %%NAME
Please note that the values you specify for any NAME="" fields and any %% variables are converted to uppercase! Therefore, NAME="NAME" and NAME="name" are identical, and %%NAME and %%name are identical.
To make a subject line work properly (as mentioned in Step 1), it must be the very first line of your text template file, it must be followed by a blank line, and it must be formatted as follows:
Subject: %%_SUBJECT
Click here for a simple yet complete example. I consider this mandatory reading.
