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
. TheSIZE
andMAXLENGTH
are optional and need not be specified. IfSIZE
andMAXLENGTH
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
andCOLS
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. IfMULTIPLE
is specified, then the resulting scrolling list will allow multiple selections. TheMULTIPLE
field is specified by using the word "mult" (case insensitive) after theSHOW
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
andCOLS
are for HTML3 browsers, but are most of the time ignored on older browsers. TheBREAK
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. IfTEXT
is not specified, then the colon can be omitted and theNAME
will be used to title 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 ATTR
s 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.
14 POD Errors
The following errors were encountered while parsing the POD:
- Around line 231:
'=item' outside of any '=over'
- Around line 254:
'=item' outside of any '=over'
- Around line 274:
'=item' outside of any '=over'
- Around line 314:
'=item' outside of any '=over'
- Around line 339:
'=item' outside of any '=over'
- Around line 388:
'=item' outside of any '=over'
- Around line 439:
'=item' outside of any '=over'
- Around line 489:
'=item' outside of any '=over'
- Around line 511:
'=item' outside of any '=over'
- Around line 531:
'=item' outside of any '=over'
- Around line 582:
=over should be: '=over' or '=over positive_number'
You can't have =items (as at line 587) unless the first thing after the =over is an =item
- Around line 716:
You forgot a '=back' before '=head1'
- Around line 968:
'=item' outside of any '=over'
- Around line 1011:
'=item' outside of any '=over'