The Format Statement

The format statement has three forms:

1. format screen [source {[path/]filename}] [nh] [literal|sub]
2. format email to {email address} [from {email address}] [subject "{subject}"] [name "{name}"] [source {[path/]filename}] [literal|sub]
3. format file {filename} [before|after "{string}"|overwrite] [chmod nnn] [source {[path/]filename}] [literal|sub]

Replace curly brackets {} and the enclosed identifier with an actual value (or field name). Everything within square brackets [] is optional. Quotation marks are required where indicated. The rules for the format after the format statement line (i.e., the format pictures, field names, and the period) are the same for each format type (screen, email, file). Format statements may not span multiple lines.

Each of the values (indicated by curly brackets {}) can be set either to a literal value or to a value from the form. For example, you could send a message to the email address entered on the form with:

format email to $email_addr

A format has three parts:

1. The format statement (in one of the above 3 forms), which begins the format
2. The format body (called the format picture), which visually describes the orgranization of the data, and resides on the lines in your configuration file between the format statement and the format terminator (or in a separate file if the source keyword is used).
3. The format terminator, a period on a line by itself.

The second two are omitted (moved to a separate file) if the source keyword of the format statement is used.

There are two types of formats which can be specified in the format statement: literal and sub. The default type is sub (if you don't specify a type). Briefly, literal works in conjunction with the source option, and means the form processor copies the data from the source file directly to the destination, as is, with no substitutions; sub means the form processor will look for field names indicated with a dollar sign ($) followed by a field name, and substitute that field's value for the dollar sign and field name.

format email to $email_address subject "Order Acknowledgement"

This would send the formatted data to the address entered on the form at the field named email_address.

format screen [source {[path/]filename}] [nh] [literal|sub]

The data defined by the format is directed to the user's screen (and thus should consist of a full HTML page, with header, footer, etc.). You may optionally have the format picture retrieved from a separate file instead of including it in-line in your configuration file, by using the source parameter after the word screen. See format email below for a more detailed discussion of retrieving format pictures from a separate file.

Technical Note - if you use Relative URLs with format screen

Use the nh (no header) keyword in your format screen statement if you want to return your own HTTP response header. This is an advanced usage and if you don't understand it, you probably won't want to use it. In a nutshell, every response from the Web server to the Web browser starts with a header (a single line of text followed by a single blank line) which tells the browser what type of data is being returned. By default, the text/html header is returned when you use the format screen statement. For example, consider the following format:

format screen
<H1>Hello world!</H1>
.

If you coded this format in your configuration file, the form processor would return the following to the browser:

Content-type: text/html

<H1>Hello world!</H1>

The form processor automatically generated the appropriate response header for you. However, if you could also code your own HTTP response header as follows:

format screen nh
Content-type: text/html

<H1>Hello world!</H1>
.

The nh keyword tells the form processor not to generate an HTTP response header, and thus the responsibility falls to you to code a valid response header in your format picture (don't forget: the response header must always be followed by a blank line!). This example produces the same output as the previous example, the only difference being that we coded the response header manually in the second example.

Another use of the nh keyword is with a Location header, as in this example which causes filename.html to be returned to the browser after the form is submitted:

format screen nh
Location: http://webcom.com/~webcom/userid/filename.html

.

Note that you must have a blank line before the format terminator when using a Location header.

format email to {email address} [from {email address}] [subject "{subject}"] [name "{name}"] [source {[path/]filename}] [literal|sub]

Example:

format email to address@webcom.com from $email_address subject "Subscription Request" name "$first_name $last_name"
subscribe
.

to {email address} is required, and defines the email address to which the formatted data is directed. Multiple email addresses can be specified by separating them with comas (no spaces).

from {email address} is optional, and defines the email address from which the email will originate (useful for feedback forms, to make the mail come from the email address entered by the user on the form, so when you reply, it goes to them, also useful for sending mail on their behalf for a subscription to an email list, etc.). If from email address is ommitted, the mail will originate from youruserid@webcom.com.

subject "{subject}" is the subject of the email. You must surround the subject with double quotes (even if you're using a field value for the subject.

name "{name}" is the name of the person from whom the email address is sent. Most email readers display the name of the person a message is from instead of the email address it came from when displaying a list of messages (in an email folder or incoming mailbox). You can use this to set the from description to anything you like. You must surround the name with double quotes (even if you're using a field value for the subject.

source {[path/]filename} tells the form processor to retrieve the format picture from the specified file instead of from the following lines in the configuration file. This can be used to use a format based upon a selection on the form. For example, you could have a drop-down listbox allowing the user to select which document they wanted mailed to them. The value of their selection would be a filename, which you'd use as the source in the formatted email to them, as in:

format email source www/$selected_file

If you use source, then the format is retrieved from that file. All the other rules about formats apply (including placing a blank line at the begining of your format picture), except the end-of-format terminator (period on a line by itself) should not be used.

SECURITY WARNING: You should always put source formats in a special subdirectory, so your format source parameter reads: source dir_name/$filename. The reason is that a hacker could construct a form almost like yours but which allowed them to specify any value (by using a text box instead of a drop-down list box for example) for the field used to determine the source file; thus they could read any file in that directory. If you prefix the source with a directory name as recommended, they will only be able to read files in that directory. If you used source=$filename, they could construct a form which submits any filename they desired in your home directory. The form processor runs under your userid when your forms are submitted, so form processor applications can grant full access to your account if you do not take such precautions (under no circumstances should you allow writing to a file whose name is determined by a form field, unless you prefix the filename with a directory).

If you use source, you cannot also include a format picture in the configuration file (unless you start another format). In other words, you must use either source or include the format in the configuration file, but not both.

Do not follow a format with a period on a line by itself (format terminator) if you're using source; the format terminator is only required if you include a format within the configuration file after the format statement.

SECURITY WARNING: do not use a form value as the filename to be written to, because even if you limit the range of values with, for instance, an option list, a hacker could construct a renegade form which replaced the option list with a text field, effectively giving them full control to insert or append text to any file. If you must use a form value in the filename, prefix it with a directory name, such as incoming/, so no matter what people can only write to files in that directory (the forms processor forbids the parent directory indicator .. in filenames, so they could not reference a directory above incoming/).

chmod nnn is optional, and defines the UNIX file permissions mask you want applied to the file. If you are appending to the file, this mask is only used to set the file permissions the first time the file is created. It does not change the permissions each time it appends to the file, so if you change the permissions on the file yourself manually, they will stay as you set them. However, when you insert into the file using the insertion point feature described above, the file must be reconstructed for each insertion. In this case, the permissions are set each time the form is submitted (since the file is re created with the new data). You can also set the permissions mask globally for your form with the chmod parameter.

Example:

format file form/guestbook.html after "<!-- This HTML comment marks the insertion point -->" chmod 755