Q. How do I use Formation to process form information?

A. Formation is one of the CGIs available on the campus web server to process form data. It's relatively easy to learn and use for anyone familiar with tag-based coding like HTML.

This page describes how to put together your own Formation files to process form data. You can use Formation to send email, save information to a file, deliver custom responses to your users, create HTML pages, collect survey data, create a guestbook, etc.

Formation will also process files which used Flexmail on the old campus web server.

General Information

The Formation CGI will activate any time the server receives a request for a file with a ".flx" or ".fcn" extension. Formation takes any data received from the form and processes it according to your instructions in the .flx/.fcn file. In the .flx/.fcn file, you can:

  • Make sure that certain fields have to be filled out, and return an appropriate error message if left blank.
  • Send email that is formatted any way you like.
  • Return an immediate customized response to the user, including any information they provided in the form.
  • Redirect a visitor to another URL.
  • Save the form data in either a text-and-tabs data file or a custom-formatted text or HTML file.

HTML Forms

There are a few things to remember when building forms for use with Formation:

  • Your form needs to point to a .flx/.fcn file in the form tag.
    Example: <form action="file_name.flx" method="post">
  • Always use the POST method
    Example: <form action="file_name.flx" method="post">
  • Give every element a name. If you don't name an item, its value won't be returned to you for processing.
    Example: <input type=text name="name" size=35>
  • Element names should only contain alphanumeric, non-whitespace characters. You can use dashes or underscores in place of white space.
    Example: <input type=text name="my_name" size=35>
  • Element names should be 25 characters or less.
    Example: <input type=text name="flex_doesnt_like_26_chars" size=35>

Replacement

Your .flx/.fcn file will contain one or more Formation commands. Some commands will include a Formation replacement. Any string of non-whitespace characters surrounded with % signs in your .flx/.fcn file will be replaced with an item from the form. The value for the input's name should be the same as the Formation variable. For instance, if your form has the following input box:

<label for="email">Enter your email address: </label><input type="text" name="email" id="email" size="40">

The following code within your .flx/.fcn file will be replaced with the contents of that field:

%email%

Built-In Variables

There are a few "built-in" items that Formation provides to give you some information about the client accessing the Flex file.

  • % _Date% contains the date sent.
  • %_Time% contains the time sent.
  • %fcn_date% contains the date and time
  • %_Referer% contains the HTML file that the person used to get to this .flx/fcn file.
  • %_UserName% contains the log-in name of the user, provided s/he had to use a username to get to this area of your server.
  • %_UserAgent% is the type of browser being used.
  • %_Address% is the host name or IP address of the user's computer.
  • %_FlexID% is a number unique to any given execution of Formation.

Formation Tags

In Formation, order is important. Formation Tags are processed in the order they occur in your .flx/fcn file. If your form has required fields, you must put the <ERROR> and <REQUIRE> tags at the beginning of your .flx/.fcn file. The other Formation tags can be used in any order after that.

<ERROR>...</ERROR>

This tag contains the HTML that is to be returned if any fields listed in the <REQUIRE> tag are empty.

<REQUIRE>

The <REQUIRE> tag specifies any fields that must contain data before the form will be processed. For example, you might require that users fill out the element named "email" in order for the form to be processed.

Example:

<require email>

To require more than one field, simply add it to the require tag: Example:

<require email name>

If a <REQUIRE>'d field contains no data, the <MAIL> and <RESPONSE> tags are ignored and the contents of the <ERROR> tag is returned instead.

You can use a series of paired <ERROR> and <REQUIRE> tags to verify each required field in a form individually and return an error message specific to the field your visitor left blank.

Example:

<error>
<h2>OOPS!</h2>
<p>Please fill out the Name field.</p>
</error>

<require name>

<error>
<h2>OOPS!</h2>
<p>Please fill out the email field.</p>
</error>

<require email>

<MAIL>...</MAIL>

The <MAIL> tag specifies the email output to send, based on the form data. It must be followed by an RFC823-compliant header. You *must* leave a blank line between the mail header and the body of the message. The message can be as long as you like, and can include information imported from the form.

Example:


<mail>
To: me@some.org
From: webmaster@www.mydomain.com
Subject: Formation is Cool

Hey! This stuff really works!

The user's comment was %comment%.
</mail>

If you don't want to send email from a .flx/.fcn file, simply omit the <MAIL> tag all together. To send more than one email message, use multiple <MAIL> tags. To send the same message to more than one person, put the extra address on the To or Cc lines of the email header. eg:


<mail>
To: me@some.org, you@some.other.org
From: webmaster@www.mydomain.com
Subject: Hello

This message will go to more than one person. You must separate the multiple addresses with a comma and a space.

</mail>

To send mail with HTML content from formation you must include the content type after the Subject line. Also, there must be an empty line & carriage return between the end of the mail header and the beginning of the mail content.

<mail>
To: me@some.org
From: %email%
Subject: Form Submitted by %name%
Content-type: text/html; charset=us-ascii

<html>
....(contents of page with HTML formatting)
</html>
</mail>

Note: Previous versions of Flexmail used a SERVER attribute in the <MAIL> tag. This is not necessary when using Formation. Formation will ignore the SERVER attribute if it's used.

<RESPONSE>...</RESPONSE>

The response tag contains the HTML that will be returned to the user when they successfully submit the form. Like the <MAIL> tag, it can contain replacement items from the form.

Example:

<response>
<center><h1>Thanks</h1></center>
Thank you for filling out our customer-feedback
form. You said:


%comment%
</response>

In this example, whatever the user entered into the form item named "comment" will be included with the response they see.

<SAVECUSTOM "file" [MODE ]>...</SAVECUSTOM>

This tag allows you to save free-form data, using both text you specify and data from a form. You could, for instance, create on-the-fly HTML documents from form data. In this example, a form with fields for a subject, name, and comment could be used to create a guest book:


<SAVECUSTOM "bigfile.html" APPEND>
<hr>
<strong> %subject% </strong> <br>
by %name% <p>

%comment%

<p>
</SAVECUSTOM>

There are three MODEs that you can use with the <SAVECUSTOM> tag. The mode controls how the file is created:

  • APPEND is the default. If the file already exists, then the data is simply appended to the end of the file. If the file does not already exist, then it is created and the data is written to it.
  • UNIQUE will guarantee that your file is given a unique filename and will not overwrite or modify any other file.
  • NEW will cause the new data to replace any old data that was already in the file. If the file does not exist, it is created.

The file specification can indicate any file in any folder within the flex file's parent folder (eg: "subfolder/mydata.txt"). You can not save data to a file outside the flex file's parent folder.

On multihoming servers, SaveData and SaveCustom will not allow you to modify/create files outside of the current host's root folder. (ie: a flex file in one virtual host cannot change the file in another virtual host's folder)

<SAVEDATA "file">...</SAVEDATA>

This command allows you to save form data in a text-and-tabs format to the file you designate. This is especially useful for collecting survey data to later import into a spreadsheet (like Excel) or data analysis application (like SPSS).

Unlike other Formation commands, <SAVEDATA> doesn't use the %...% syntax to indicate where form data should be substituted. Instead, Formation will replace any characters it finds with form data, and replace all white space with tabs.

For example, if you had a form where a user entered their name, address, city, and state, you could save that file with the following lines in a Flex file:

<SAVEDATA "mydata.txt">
name
address
city
state
</SAVEDATA>

The file specification can indicate any file in any folder within the .flx/.fcn file's parent folder (eg: "subfolder/mydata.txt"). You can not save data to a file or folder outside the .flx/.fcn file's parent folder.

<REDIRECTTO HREF="URL">

Instead of returning an HTML response to the user, you can redirect the user to another URL. You can use either a full URL, or a path relative to the web server root. This must be used in place of the <RESPONSE> tag.

<REPLACE>x</REPLACE>

Sometimes it is not convenient to use the %...% notation because it can interfere with some URL-encoded information. You can select a character other than % as the delimeter using the <REPLACE> tag. The following line will change the delimeter from % to ~ (tilde).

<REPLACE>~</REPLACE>