EOS Flexmail CGI

Using Flexmail

Flexmail is an extremely flexible, powerful, and easy tool for building web pages. With a bit of creativity, there are literally thousands of ways you can use flexmail.

General Information

The Flexmail plug-in will activate any time the server receives a request for a file with a name ending in ".flx". The Flexmail plug-in takes any form data received from the client and processes it according to your instructions in the flex file. In the flex file, you can:

Make sure that certain fields have to be filled out, and return an appropriate error message if they are left blank.
Send email that is formatted in any way you like.
Return a customized response to the user, including information they provided in the form.
Instead of returning an HTML page to the user, you can redirect them to another URL.
Save the form data in either a text-and-tabs data file or a free-form text file

Example flex files for various applications are included with both the demonstration and full versions of Flexmail.

FORMS

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

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>

REPLACEMENT

Any string of non-whitespace characters surrounded with % signs in your flex file will be replaced with an item from the form. For instance, if your form has the following input box:

Enter your email address: <input type=text name=email size=40>

The following code within your flex file will be replaced with the contents of that field:

%email%

Built-In Variables

There are a few "built-in" items that Flexmail provides to give you some information about the client accessing the Flex file. Use these tags with %...% around them:

_Referer contains the HTML file that the person used to get to this Flex 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 Flexmail

<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: Flexmail is Cool Hey! This stuff really works! The user's comment was
%comment%.
</mail>

If you don't want to send email from a Flex file, simply omit the MAIL tag alltogether. To send more than one email message, use multimple 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>

Note: Previous versions of Flexmail used a SERVER attribute in the MAIL tag. This is no longer a part of the Flexmail syntax, and Flexmail will ignore the SERVER attribute.

<RESPONSE>...</RESPONSE>

The response tag contains the HTML that will be returned to the user. 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.

<REQUIRE>

The reqire 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.

<ERROR>...</ERROR>

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

<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 guestbook:

<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 gurantee 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.

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

This command allows you to save form data in a text-and-tabs format to the file you designate. Unlike other Flexmail commands, SAVEDATA doesn't use the %...% syntax to indicate where form data should be substituted. Instead, Flexmail 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 flex file's parent folder (eg: "subfolder/mydata.txt"). You can not save data to a file outside the flex file's parent folder.

<REDIRECTTO HREF="URL">

Instead of returning an HTML response to the user, redirect the user to another URL. You can use either a full URL, or a path relative to WebSTAR.

<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>

Examples:
Using Flexmail for email responses.

Using Flexmail to append pages on the fly.

Using Flexmail to update pages on the fly.