NAME

Former - Generic CGI script for processing forms

SYNOPSIS

http:/cgi-bin/former/forms/form.conf

DESCRIPTION

Former is a CGI script that is used to produce and process forms on a WWW server. It has been designed to allow quick and easy implementation of forms without the need to rewrite a CGI script everytime.

Each form consists of two files: the configuration file and the form definition file (FDF). The configuration file holds the basic state information (i.e. which actions and forms get called in what order) and is specified in the URL. The configuration file is setup very much like a Windows INI file, and is only required to have the [Former] section. A simple configuration file might be:

        [Former]
        
        Form Definition = /www/forms/form.def
        Form = entry
        
        [entry]
        
        Form = reply
        Action = reply

Whenever Former starts up, it must always find the file specified by the Form Definition in the above. This file is the FDF that contain the entries for the forms and actions. The FDF file is described in the section "Form Definition File Format".

After the FDF is read and processed, Former will then determine if this is the first time it has executed. If so, it will use the entries under the [Former] section for processing. If Former has executed before, then it will use the name of the previous form for the next section that needs to be processed.

In the above example, When Former is first called, it will display the entry form. In this case, there was no action associated with the entry form. After the user presses the submit button, Former determines that is it had just done the entry form. As a result, it begins to process the entries in the [entry] section. Former always processes the action field first followed by the form field. In this case, the reply action is performed (as it is specified in the FDF), and then the reply form is sent to the browser.

In future revisions of Former, the configuration file and FDF will be the same file.

Form Definition File Format

The actual CGI form is defined in the form definition file (FDF). This file contains three types of sections: "Form Format", "Action Format", and "Field Format". There can be multiple form and action sections, but only one field section. Each of the sections will be described in detail below.

To keep the FDF from getting too cluttered, you can use a seperator line to keep the sections from getting mixed together. The seperator line looks like:

        %%-----------------------------%%

The number of dashes is trivial; just as long as there is more than 1. This line should not be confused with the action seperator line (more later).

Form Format

A form section looks like the following:

        %%Form:NAME%%
        
        HTML code and form definitions
        
        %%Form%%
        

The NAME is the symbolic name that this form is known as. It is the same name that is used in the configuration file to call the form.

What is included between the two %%Form%% lines is standard HTML. The only exception is for the form elements. Each type of form element is described below.

Text Entry

+ Text

        %%Text:NAME:SIZE,MAXLENGTH%%

The generic text entry box is created with the Text definition. This creates a text entry that is associated with NAME. The SIZE and MAXLENGTH are optional and need not be specified. If SIZE and MAXLENGTH are not specifed, then the final colon does not need to exist.

+ Textarea

        %%Textarea:NAME:ROWS,COLS%%

The Textarea definition creates a multi-row text entry box. ROWS and COLS are mandatory for Textarea. This release does not support any default values for the Textarea definition.

+ Password

        %%Password:NAME:SIZE,MAXLENGTH%%

The Password definition is exactly the same as the Text definition. Using the Password definition allows text to be entered, but not seen in the text field.

Lists, Checkboxes, Menus, and Radio Buttons

The basic form for all these definitions is

        %%TYPE:NAME:OPTIONS
        {val1}label1
        {val2}label2
        {val3}label3
        %%

The TYPE field must be one of Popup, List, Checkbox, or Radio. NAME is the name of the field on the form. OPTIONS is specific for each field type, and should conform to the specifications below. If there are not any options specified, the colon between NAME and OPTIONS can be omitted.

The value-label pairs are as they are shown above. The values are always surrounded by curly braces ({}) --even when used in the OPTIONS field-- followed by the label that should be associated with the value.

+ Popup

This type produces a popup menu on the HTML form. OPTIONS in this case specify the default label to show when the form is displayed. The value for the the default label must be surrounded by curly braces ({}).

+ List

The List type will produce a scrolling listbox. The OPTIONS parameter is specified as:

        {VAL}SHOW MULTIPLE

The VAL is optional and should contain the default value for the list. If a default value is not being specified, the curly braces ({}) should not be supplied. Multiple default values can be specified one after another; each value must be delimited by curly braces. SHOW allows the number of entries to be shown to be specified. If MULTIPLE is specified, then the resulting scrolling list will allow multiple selections. The MULTIPLE field is specified by using the word "mult" (case insensitive) after the SHOW paremeter.

+ Checkbox

This is used to create a single checkbox or a group of checkboxes that correspond to a single field for the displayed form. The OPTIONS parameter is specified as:

        {VAL}COLS,ROWS BREAK

The default values are specified the same way as List default values. The ROWS and COLS are for HTML3 browsers, but are most of the time ignored on older browsers. The BREAK parameter is used to place line breaks between each checkbox. It is enabled by using the word "break" (case insensitive) after the rows and columns parameters.

+ Radio

The radio button specification is exactly like that of the checkbox specification. The OPTIONS parameter is specified in the same manner.

Action Buttons

The action buttons allow you to specify the submit and reset buttons for a form. The action buttons take two forms: submit and reset. The submit button sends the information entered into the form to the server to be processed by a CGI script. The reset button causes the form to be reloaded with the values it had before any changes were made.

+ Submit

This action produces the submit button, and places TEXT as the description on the button. The submit definition is as follows:

        %%Submit:NAME:TEXT%%

The NAME is used to allow multiple submit buttons on the same form. TEXT allows the button to be titled with the specified text. If TEXT is not specified, then the colon can be omitted and the NAME will be used to title the button.

+ Reset

        %%Reset:TEXT%%

Create the reset button. Use TEXT as the decription on the button.

Miscellaneous

+ Hidden

        %%Hidden:NAME:VALUE%%

The hidden definition allows additional information to be include into the form. NAME is how the information will be accessed from the CGI script. VALUE if defined will be what the value is set to no matter what the value currently is.

Field Format

Fields are not fully implemented in this release.

The Field section allows attributes to be set to a particular field in a form. Below is a list of currently implemented field attributes:

Does not allow a form to proceed until the field has an entry.

+ Upcase

Converts the contents of the field to uppercase.

+ Lowcase

Converts the contents of the field to lowercase.

+ Blank

Undefined at this time. =back

The Field section looks like:

        %%Fields%%
        
        FIELD:ATTR
        FIELD:ATTR ATTR
        FIELD:ATTR,ATTR
        
        %%Fields%%

FIELD is the name of the field to associate ATTR with. Multiple ATTRs can be seperated by anything (space, comma, colon, flat colon, etc.).

Action Format

The action format section specifies how what actions are to be performed when a form has been submitted. Each action can consist of a number of commands (command sets). Below is an example of an action section.

        %%Action: NAME%%

        COMMAND ARGS
        %----%
        COMMAND
        %----%
        COMMAND ARGS
          DATA
        %----%
                
        %%Action%%

Action sections start with the %%Action:NAME%% line. The NAME specify a title for this action. NAME is how this action is refered to in the configuration file.

Each command is seperated by a command seperation line (%---%). This line should not be confused with the general seperator line that have two percent marks (%) at each end. As with the general seperator line, the number of dashes does not matter, as long as there is one or more.

When the command has a data area (such as the Mailto action), the fields in the CGI form can be substituted into the data area. The fields must be delimited with two percent marks on either side of the field name. The substitution begins and ends with the percent marks, so the field can be embedded into the data area with no disruptive effects.

The entire definition is complete when the %%Action%% line is given.

Below are the supported commands in this revision of Former.

Mailto

The Mailto action allows an email message to be generated. The format is very simple and straight forward. The format is as follows:

        Mailto: EMAIL
        RFC822 HEADERS
        
        BODY OF MESSAGE
        %---%

EMAIL specifies a list of email address (seperated by commas) to send the message. The next couple of lines consist of standard RFC822 headers. The most common headers that will be used will consist of:

        Subject: SUBJECT
        From: EMAIL
        Return-Receipt-To: EMAIL
        Cc: EMAIL
        Bcc: EMAIL

After the headers there must be at least one blank line to seperate the headers from the body of the message. You may include CGI fields in the body of the message.

Sendback

This command will simply provide a way to specify which form to send back to the browser. It is simply invoked by saying:

        Sendback: FORM

Where FORM is the symbolic name of the form desired to be sent.

Store

The Store action will allow the data that has been collected to be placed in a database or a file. The format for this group of commands is as follows:

        Store:TYPE:ARGS
        
        Text/data to store
        
        %------------%

TYPE is one of the following types. ARGS are the arguments that the TYPE needs to have specified.

+ Store:File

This module will append the text to a specified file. At this time, there is no file locking capabilities on the file being written.

+ Store:Msql

The module will allow access to a mSQL database. When using this command, the following structure must be used:

        Store:Msql:HOST,DATABASE
        SQL statement
        %-----%

HOST is the hostname of the machine which has the database server running. DATABASE is the SQL database name that the SQL statement should be preformed on. The data portion of the command (SQL statement) is a valid SQL statement that will be sent to the mSQL server after the field substitution has occured.

cpanm ConfigFile

perl -MCPAN -e shell
install ConfigFile