Art.Net Help Pages: Using Forms on Art.Net

Our server supports a forms interface that allows for collecting data entered into an html form by a user. The data can be appended to a file in your account, and/or e-mailed to you. The instructions below assume you know how to write HTML forms. If not, see the Beginner's Guide to Writing HTML.

This new form program is called form, and is recommended for all new form applications. Documentation for the old form program is still available.

Action URL

To use our forms interface, you must use the POST method of submitting the form. The action for the POST method will point to a URL that processes the form data. The URL specifies both a program that processes the form, and the location of a configuration file that tells it how to process the form. For example, your HTML form would start with the following:

<form method="POST"
action="http://www.art.net/cgi-bin/form/dir/filename">

In this example, cgi-bin/form is the name of our forms processing program. dir is replaced by your directory (ftp account) name, and filename is the name of a configuration file that will be used by the forms processing program. You can have different configuration files for each form, or use the same one for multiple forms.

Configuration File

You must create the configuration file and place it in the path you specified in the action URL mentioned above. The configuration file specifies a number of commands and other files used in processing the form. It specifies the page that will be returned to the user after the forms processing is finished. Additionally, the configuration file can contain commands to append the form data to a file, email the form to a specified address, and also perform various checks on data entered in the form. The configuration file commands are:

Filenames

Note that any filenames specified in the configuration file are always relative to your top-level directory. So, if you have a mail template file named info.txt in your main directory, you would use the command mail info.txt, but if you place the template file in a subdirectory called forms, then it would be specified as forms/info.txt.

Template Files

A template file is a standard text or html file that is used to tell the forms program how to format output to a browser, file, or email message. The text of the template file is copied character for character, replacing any occurrances of words surrounded by curly-braces with the corresponding field value from the form input data. You can also use any of the variables from the var program. For example, a template file such as: 
A user named {name} from {REMHOST} filled out this form
and left his number as {number}.
Would be filled in with the form data, and the result may look like: 
A user named Joe from FOO.COM filled out this form
and left his number as 123-4567.

Return Command

The return command is followed by either a fully specified URL (one that starts with http://) or a template file name. If a URL is specified, then the browser is told to retrieve that URL after the form is processed. Otherwise the template file is processed and returned to the user. Many older Mosaic based browsers can not handle being returned a URL to retrieve and will display an error to the user after the form is processed. If you want your form to work with all broswers then you should use the name of a file instead of a fully-specified URL.

File Command

The file command is followed by the name of an output file and the name of a template file. When a form is processed, the template file is used to format the form data that will be appended to the output filename listed. The output file can be a private file in your directory where you accumulate the form data. It can also be used to accumulate form data formatted as html code, and the file could be displayed to users via another one of your web pages. One use for this is when making guestbooks that users can sign. You may have up to two file commands in the config file.

File Output Notes

If you use the output file command, and the file does not exist, it will automatically be created with the file protections "rwx------" (ie. only you will be able to read it). If the file already exists, new data will be appended to it, and the file protections will not be changed. This would allow you to setup a world-readable file other users can read, such as for guestbook applications.

Mail Command

The mail command is followed by the name of a template file, which specifies the format of the entire mail message, including the message headers. This allows you to not only format the message, but to set up the sender, recipients, and subject of the message, and any other special headers you might need. However, it is extremely important to make sure your template contains valid header formats for the mail system. A sample mail template may look like this: 
From: <{email}>
To: <yourname@someplace.com>
Subject: {interest}

{name} left the following message:
{message}
The example assumes you have made input fields on your form called email, name, interest and message. All mail templates must include a From and To header at a minimum. A Date header with the current date will automatically be added to the message. Other headers you may want to use include Cc to send a copy of the message to another recipient, and Bcc, to send a hidden copy of the message to another recipient. Receipent addresses should be enclosed in angle brackets like <user@hostname>. There must also be a blank line between the headers and the message body.

Make sure you upload the template file to your directory using Text or ASCII mode in FTP. In order to make sure a valid email addresses is entered onto the form by the user, you may want to use the check command listed below. If you don't have an email address field on your form, you can always set the From header to your own email address (the same as the To header). You may have up to two mail commands in the configuration file. One might be used to send the form data to you, while another is used to send a confirmation message back to the user.

Check Command

The check command is used to test a form input field for certain conditions, and ask the user to fix the problem if an entry is not correct. You can have as many check commands in the config file as you need. The check command is followed by the name of a form input field, the type of check to do, an error message to display to the user, and optionally, the name of a template file for displaying the error message.

Check Types

The types of input checking available are one of:

Error Message

The error message must be enclosed in double-quotes. It can be as long as you want but there must not be a carriage-return inside the quotes. The message may contain text or html code. If you do not specify an error message template file (next section), then the error message will be inserted onto a generic error page displayed to the user, telling them they made a form entry error, displaying your message, and asking them to press the Back button to correct the error.

Error Template File

If you don't want your error message displayed with the generic error page created by the form program, then you can specify the name of a template file used for displaying your error message. The template file is a standard html page and you can use any of the form input fields or predefined variables as in the other template files. In addition, the error message you specify above can be displayed using the variable named ERROR_MESSAGE.

Check Command Examples

For example, you might have the following check commands in your form configuration file: 
check name not-empty "Please enter your <b>name</b> on the form."
check email email-address "Please enter a valid email address" formerr.txt
In this case, if the name field on your form is left blank, the generic error message page will be displayed to the user, along with the specific message you listed. If the email field on your form does not contain a valid looking email address, then your template file formerr.txt will be displayed to the user. Your formerr.txt file can contain the variable {ERROR_MESSAGE} which will be replaced by the message "Please enter a valid email address". Note that you can also use the same error template file for different check commands.

Return to Help Pages