FPU Help
Admin Login
NAUTICAL Form Processing Utility (FPU)

Contents:
Check your stats.

Note: Throughout this Help page, form element examples in red indicate form elements that are required for the FPU to work properly. Form element examples in green indicate optional elements.

About the Form Processing Utility

The Form Processing Utility (FPU) accepts input from an HTML form and places the contents into an email. By placing hidden fields in the form being processed, the FPU can perform advanced formatting of the email text, attach an uploaded file to the email, customize the response presented to the form submitter and even count how many times a given form is submitted and when the last submission occurred.
Top

FPU Basics

HTML forms are created by using various types of elements, or fields, such as textboxes, checkboxes, etc. Each element in a form has attributes such as the name and value. The form element itself has several attributes such as name, method, target and action. Before the FPU can be used to process your form, you have to get your form to the FPU. This is accomplished by setting the form action and method attributes as follows:

<form method="post" action="https://nautical.uwf.edu/utility/processform.cfm">

The FPU uses the hidden form element to determine what the user wants the FPU to do with the form submission. In some cases, a hidden element name tells the FPU everything it needs to know and in other cases the name tells what needs to be done and the value tells the FPU what to do it to. For example, placing the following hidden element in a form tells the FPU to send the email to jdoe@uwf.edu and ssmith@students.uwf.edu.

<input type="hidden" name="mailTo" value="jdoe@uwf.edu,ssmith@students.uwf.edu ">

The FPU detects the name mailTo and knows to look in the value attribute of the same element to determine the recipients of the email.

The FPU naming convention for element names it considers meaningful is:

  • Elements beginning with a letter of the alphabet apply to the whole form.
  • Element names beginning with the name of another element and having a suffix of _heading, _delHd, _delHdAndRtn, _delStr or _dupTxt apply only to the element named by the part before the suffix.
Top

NAMES ARE IMPORTANT!

There are three things to pay particular attention to when using the FPU:
  1. Certain element names are reserved because they have special significance to the FPU. Reserved means they cannot be used in your form except as described on this help page. The reserved element names are: mailto, mailsubj, formname, mailfrom, formowner, owneremail, fieldfilter, referto, tracking, suppressBlanks, ccto, ccANDfrom, upldFile and altfldlist. The purpose of each is described in this document.

  2. Certain characters cannot be used in element names. Since the FPU is written in the ColdFusion Markup Language (CFML), the names must conform to ColdFusion variable naming syntax as follows:
    • Element names must begin with a letter, which can be followed by any number of letters, numbers, or the underscore character.
    • Element names must be all one word (no spaces).
    • Element names cannot have spaces or special characters (e.g. #, @, *, -, %, etc.). For example, fname, FirstName, and First_Name are valid, but 1stName, WhatAName!, and User-Name are not (1stName does not begin with a letter and WhatAName! and User-Name both have special characters).

  3. The formOwner, formName and ownerEmail fields have length restrictions on the values. They are:
    • formName - 120 characters.
    • formOwner - 120 characters.
    • ownerEmail - 80 characters.
Top

Minimum Requirements to use the FPU

The form attributes method and action and mailTo, mailfrom and mailsubj hidden elements are all that is required to use the FPU. The form attributes method and target send the form to the FPU in such a way that the FPU knows where to look for the form information. The mailTo, mailfrom and mailsubj elements designate the email recipient(s), who the email appears to be from and the subject lines, respectively. These are the only elements required to use the FPU; the rest are optional.

<form method=post action="https://nautical.uwf.edu/utility/processform.cfm">
<input type=hidden name="mailTo" value="destination@uwf.edu">
<input type=hidden name="mailFrom" value="someAddress@uwf.edu">
<input type=hidden name="mailSubj" value="Student Registration Submission">

Hint: If you want the email to be from the form submitter, so that you can reply to them without having to type their email address, make the mailFrom field a required text field in the form where they can enter their email address. The steps necessary to specify a field as required are described in the section on Requiring Input and Validation.

  • The form method attribute value MUST specify POST (e.g. <form method="post" ...).
  • The form action attribute value MUST specify "https://nautical.uwf.edu/utility/processform.cfm"
  • The form MUST contain at least the THREE hidden fields mailTo, mailFrom and mailSubj.
  • The names of hidden fields used for the form processing utility must appear EXACTLY as described in this document.
  • Multiple recipients specified in the mailTo hidden field MUST be separated by commas (e.g. ...value="recipient1@uwf.edu, recipient2@uwf.edu,...")
  • If used, the referTo field value MUST contain a complete URL (e.g. value="http://nautical.uwf.edu").

Note:

  1. The hidden variables used by the FPU are not listed in the email except for the mailTo, mailfrom and mailsubj as previously discussed.
  2. You can use other hidden fields in your form. They will be listed in the resultant email message just like any other field in your form (unless you suppress them).
Top

Element Placement

The hidden elements can go anywhere inside the form tags of your form. However, it will make your form easier to develop and maintain if you place all the global (apply to the whole form) hidden tags together and place the tags applicable to only one field with the field to which they apply.
Top

Customizing Acknowledgement

The standard acknowledgement is a page displaying:

Thank you. Your Submission has been forwarded for processing.

This feedback can be customized using the following three elements:

<input type=hidden name="referTo" value="http://anywhere.com">
<input type=hidden name="formName" value="Student Registration">
<input type=textbox name="ccto" size="40">
<input type=textbox name="ccAndFrom" size="40">

The formname element will customize the FPU acknowledgement page by substituting the formName element value for the word "Submission" in the message. Using the value "Student Registration" as in the example above would cause the acknowledgement message to read:

Thank you. Your Student Registration has been forwarded for processing.

The referTo element allows you to send the user to any URL after submitting the form. For example, you could create your own acknowledgement page on your server and use that URL as the referTo value. The referTo element overrides the formName element so that a form submitter would go directly to the provided URL without seeing the FPU acknowledgement. It does not cause a problem to specify both the referTo and formName elements and may be necessary to take advantage of other FPU features.

The ccTo element sends a copy of the email to the associated value. The example above uses an element type of textbox instead of a hidden field allowing the submitter to enter their email address and receive a copy of the resultant email. Their copy would be identical to the one received by addresses specified in the mailTo element. The ccto sends a separate email to the specified address so the recipient does not appear in the cc address line of the email received by the addressees designated in the mailto field. The ccAndFrom element is exactly like the ccto, except that it also causes to email to be "from" the email address supplied. Using the ccAndFrom allows a recipient to reply to the submitter without having to type in their email address.
Top

Counting Submissions

If the formOwner element is present, form submissions will be counted and the date of the last submission recorded in a database. It is recommended that the formName element also be used because the formOwner and formName element values are used together to uniquely identify the form. Then, if you have several forms and give each a different form name, you can specify the same owner on each form and collect submission counts for each different form. To view the submission count for forms already using the FPU, click here.

<input type=hidden name="formname" value="Student Registration">
<input type=hidden name="formowner" value="Allison Smith">
<input type=hidden name="owneremail" value="owneremail@uwf.edu">
Top

Submitter Identification and Time Stamping (Tracking)

The identification of the submitter only consists of the Internet Protocol (IP) address. It should not be used in lieu of obtaining name, SSN, or other information. IP addresses can be traced to a specific computer from which the form submission originated so could be used to determine the origin of a submission in case of inappropriate language or threatening submissions. Use of the tracking feature causes the submitter’s IP address and the date and time of submission to be appended to the bottom of the resultant email. Placing the tracking element with a value of "on" as in the example below turns on tracking:

<input type=hidden name="tracking" value="on">
Top

Formatting Email Text

Without applying any of the following email formatting techniques, the email will simply list the form fields and their associated values, one field to a line, in the order they appear on the form. For example,

FIRSTNAME: Bill
LASTNAME: Johnson
DOB: 1/29/54

As described below, the FPU makes it provides extensive email formatting capabilities.

The discussion of formatting elements will refer to this example form:

<form>
First name: <input type=text name="fname" size=40>
Last name: <input type=text name="lname" size=40>
Date of birth: <input type="text" name="dob" size=15><br>
<input type=submit value=Submit>
</form>

Which yields this form:

First name:
Last name:
Date of birth:

Suppressing Blank Fields

The text of the email containing the form data can be formatted using the suppressBlanks element and other elements which begin with a form element name and then append _heading, _delHd, _delHdAndRtn or _delStr to the end. As discussed in the naming conventions section of the FPU Basics section, suppressBlanks is not prepended with an underscore and therefore applies to the entire form.

Placing the hidden element named suppressBlanks causes any field left blank by the submitter to be omitted from the email. Without suppressBlanks, if the submitter (Bill Smith) omitted his first name, the output would still print the field name, but would print nothing after it like this:

fname:

lname: Smith

dob: 12/10/1961

Turning on suppressBlanks like this:

<input type="hidden" name="suppressBlanks">

would suppress printing of ALL element names where no input had been provided (remember suppressBlanks affects the entire form). The output using suppressBlanks would appear as:

lname: Smith

dob: 12/10/1961

The remaining text formatting elements apply only to the form element whose name they reflect.

Continuing to use the fname, lname and dob elements shown above, suppose you wanted to suppress printing of only some headings if the submitter didn’t fill in the form field. The _delStr works the same as suppressBlanks except it applies only to the element whose name precedes the _delStr. For example, to suppress only the dob heading if the submitter left it blank, but still display the two name related headings even if they weren’t filled in would be implemented as follows:

<input type="hidden" name="dob_delStr">

If the submitter filled in only his last name in the form, leaving the first name and date of birth fields blank, the output would look like this:

fname:

lname: Smith

Top

Replacing/Suppressing Headings

Besides making the email look nice by selectively leaving out blank fields, suppose you want to polish it a bit by replacing the headings (element names) fname, lname and dob with something easier to read like this:

First name: Bill

Last name: Smith

Date of birth: nn/nn/nnnn

Since you cannot use spaces in form element names, you can’t accomplish this by just naming the elements "First name:", etc. Instead you create a hidden field named fname_heading and set the value attribute to the heading you would like displayed in the email. The value attribute CAN contain spaces, or any of the other special characters that form element names cannot have. The resultant hidden field would look like this:

<input type=hidden name="fname_heading" value="First name:"><br>

The FPU understands fname_heading means it should replace fname with First name: in the email.

Two other FPU formatting options dealing with the heading are _delHdAndRtn and _delHd. Notice in earlier examples of the email output, each form element is printed on a line by itself. In other words, each element is printed out and followed by a return. As you might guess, _delHdAndRtn suppresses printing the heading and the return, allowing multiple values to be printed on one line, whereas _delHd only suppresses the heading. Please note that suppressing the heading only suppresses the original heading, not a heading specified using the _heading element. These two formatting features could be used in combination with the _heading to change a heading and print multiple fields on a single line like:

Full name: Bill Smith
Date of birth: mm/dd/yyyy

Changing the heading to "Full name:" and putting the first and last names on the same line would be accomplished using the following code:

  1. <input type=hidden name="title" value="Full name: "><br>
  2. <input type=hidden name="title_delHdAndRtn"><br>
  3. First name: <input type=text name="fname" size=40> <br>
  4. <input type=hidden name="fname_delHdAndRtn">
  5. Last name: <input type=text name="lname" size=40> <br>
  6. <input type="hidden" name="lname_delHd">
  7. Date of birth: <input type="text" name="dob" size=15><br>
  8. <input type="hidden" name="dob_heading" value="Date of birth:">

Lines 1 and 2 will cause "Full name: " to be printed on the first line of the email and the return to be suppressed so the next field will appear on the same line. Line 3 displays a form textbox for the first name. Line 4 tells the FPU to suppress printing the fname heading and to suppress the return after the fname value is printed. Line 5 displays the last name form textbox, lname. Line 6 tells the FPU to suppress printing the heading for the lname element, but leave the return afterward so that dob will be printed on the next line down. Line 7 displays the dob textbox and line 8 says to replace the dob heading with the string "Date of birth: "

Top

Requiring Input and Validation

Form field validation is actually inherent in the ColdFusion language so this section provides a brief description of how to use the ColdFusion validation features and provides a link to a more complete discussion in the ColdFusion documentation. Input validation works exactly like the FPU formatting discussed earlier in that it uses a hidden field, named similar to a form field, possibly with a value attribute which provides additional information. The validation provided is twofold. First you can make a field "required", meaning that the submission will be rejected and the user given a message if the field is left blank. Second, it can force the submitter to enter data in a specified format such as date, numeric, or numeric within a specified range.

The format for specifying a field as required is:

<input type="hidden" name="fname_required" value="You must enter your first name.">

The value attribute is not required, however, it is recommended as it can present a more meaningful error message than a generic "An entry is required."

The format for requiring the data to be a date is:

<input type="hidden" name="dob_date" value="This is not a valid birth date.">

ColdFusion will interpret most common date formats as a valid date, for example, 9/1/98; Sept. 9, 1998).

The format for requiring the data to be an integer is:

<input type="hidden" name="ssn_integer" value="you must enter a number for the SSN field.">

A complete discussion is available in the ColdFusion documentation located here.

Top

Duplicating Selected Fields

Any form field can be included in a separate block of text that will be appended to the bottom of the email message. The method for identifying fields to duplicate is to create a hidden field, named after the field to duplicate with a _dupTxt suffix. Suppose you want to duplicate the fname element. This can be accomplished as follows:

<input type=hidden name="fname_dupTxt">

Top

File Uploading

The FPU supports forms that allow the submitter to upload a file (size limited to 150KB) and attach it to the email. Use of this feature requires these three steps:

  1. The form attribute ENCTYPE must be set to "multipart/form-data".
    <form method=post enctype="multipart/form-data" ...>
  2. The form file element must be named "upldFile".
    <input type=file size=30 name="upldFile">
  3. The form must contain a hidden element named "altFldList" with a value attribute containing a comma delimited list of all non-formatting related form element names (less the upldFile element name).
    <input type=hidden name="altFldList" value="fname,lname,dob">
Note in step 3 that altFldList does not list the upldFile element name or any of the formatting related field names (suppressBlanks, fname_delHdAndRtn, etc.). If a user uploads a file larger than 150KB it will not be attached to the email, but an advisory message is inserted in the email noting that the user attempted to attach a file but it was too large. Also, the file is not attached to a ccTo email (if it exists).
Top

Tips and Tricks

  • You want the Email to be from the submitter and the submitters email address displayed in the email body.

    You can control who an email is from by using the mailFrom form field. The value of the field causes the generated email to be FROM the specified email address, however, the mailFrom field value is not displayed in the email body. This tip uses Javascript to make the email from the submitter and still display their email address in the email body without having them enter their address twice.

      <SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript">
      <!--
      function copyField(){
        document.testform.mailFrom.value=document.testform.Originator_email.value;
      }
      //-->
      </SCRIPT>
      .
      .
      .
    <form name="testform"...onsubmit="copyField();">
    <input type="Text" name="Originator_email" size="20">
    <input type="Hidden" name="mailFrom" value="">
    

    This solution is implemented by following these steps:

    • Place the Javascript code above inside the <HEAD> element of the page containing the form.
    • Make sure the form definition includes a NAME attribute (testform in the example).
    • Add a call to the OnSubmit method in the form definition to call the Javascript copyField() function as in the example above.
    • Inside the form define a textbox field in which the submitter will enter their email address.
    • Make the mailFrom field a hidden field and leave the value blank.
    • Change the Javascript as necessary to use the form name and field names in your form.

    When the user submits the form, the Javascript function copies the email address specified in the textbox to the mailFrom form field. When the FPU receives the submission, it will process the mailFrom field as it normally does, making the email be FROM that address and it will put the textbox field name and value in the body of the email message.

    Notes:
    1. Javascript is case sensitive. MailFrom and mailfrom are NOT the same thing. This is also true for the form name.
    2. The Javascript code provided above will be looking for a form named testform and fields named mailFrom and Originator_email, exactly as in the sample code and form definition. If you change the name of the form, or the form fields, you will need to change the corresponding part of the Javascript code (keeping in mind note 1).
    3. The mailFrom field name should not be changed as the FPU looks specifically for that name to determine who the email should be from.

Top