Configuring form.cgi
form.cgi is a perl5-coded CGI that accepts user input from
dynamically-generated HTML forms to create "databank entries" that can
then be viewed, searched, and edited. It is configured to have a
specific personality by means of a configuration file. This document
describes in detail how to create that file and briefly how to use the tool.
Background
Below is a little exposition of some of the concepts behind the tool.
- roles
- A key concept is that there are three distinct roles for users of the
resource:
- data providers create, delete, and edit entries
- clients browse and search entries
- administrators delete entries, change passwords, change keys,
and regenerate HTML files
- persistant storage
- Currently, data is always stored in a set of DBM files, each of
which is tied to a perl hash. There is also a per-entry HTML file and
an index of those files, but those contain no unique data, and can be
reconstructed on demand as an administrative action.
- authentication
- Any of the users of the tool may be required to authenticate. For
data providers, that might mean providing a made-up password at
record creation (or edit) time and using the built-in authentication,
or it might mean using external authentication such as basic or
CSENetID auth. Or there might be no authentiation for data
providers. For administrators, it might mean using external auth or a
pre-set password with the tool's built-in authentication. For
clients, the only option is external authentication.
- configuration
- The PATH_INFO mechanism is used to find the
configuration file, which is then read via the perl require
mechanism. That means that the tool needn't be modified or relocated
to find its configuration file, and that the configuration file must
be valid perl that returns a non-zero value.
- security
- Security is provided by requiring that the configuration file be
owned by the user running the CGI (typically nobody) and not
be world-writable.
- invoking
- The mode the CGI script operates in is controlled by the URL:
| |
create/edit entry |
.../form.cgi/<path-to-config>/action=entry |
| |
search |
.../form.cgi/<path-to-config>/action=search |
| |
administer |
.../form.cgi/<path-to-config>/action=admin |
Basic Configuration
Below is a list of the general goo that must or can appear in the
configuration file to control behaviour. Unless specified, optional.
Required
- $resource
- This string is used in various places to describe the application.
Required.
- $admin
- Email address to which comments are directed. Required.
- $path
- Full path to directory where the persistant data is stored. Required.
- $fURL
- URL of index of entries. Required.
- $fpath
- Full path to directory containing HTML files. Required.
- $ereturn
- URL of "home" for data providers. This is used for a lot of
links and redirects. Required.
- $ereturn
- URL of "home" for clients. This is used for a lot of links and
redirects. Required.
Appearance
These relate to the appearance of pages.
- $bgcolor
- Background color (bgcolor) for the <body> of all
pages, defaulting to #ffffff (white).
- $fontColor
- Text color (text) for the <body> of all
pages, defaulting to #000000 (black).
- $link ($vlink)
- Link (visited link) color for the <body> of all pages,
defaulting to #3300ff (#330099).
HTML
There are a lot of variables that control HTML chunks- mostly
header and footer- of various screens and output files. In general,
there are default values that are used if you don't define your own
values.
| Variable | Meaning |
|---|
| $entry_heading |
Heading and footer for an HTML file containing an entry. |
| $entry_footer |
| $form_heading |
Heading and footer for the data entry form. |
| $form_footer |
| $index_heading |
Heading and footer for the index page. |
| $index_footer |
| $search_heading |
For the search entry form. |
| $search_footer |
| $search2_heading |
For the search results page. |
| $search2_footer |
| $intro_heading |
For the initial form that data providers see. |
| $intro_footer |
| $update_heading |
For the screen where an existing record is selected for
updating. |
| $update_footer |
| $update2_heading |
For the screen presented after an update operation. |
| $update2_footer |
| $delete_heading |
Heading, footer for page from which
an administrator selects records for deletion. |
| $delete_footer |
| $cpasswd_heading |
For the password-changing screen, which only administrators
ever see. |
| $cpasswd_footer |
| $ckey_heading |
For the administrative key-changing screen. |
| $ckey_footer |
| $accepted |
Entire HTML screen displayed after a successful record submission by a
data provider. |
| $deleted |
Entire HTML screen displayed after a successful record deletion by a
data provider. |
| $changed |
Entire HTML screen displayed after a successful password change by a
data provider. |
| $kchange |
Entire HTML screen displayed after a successful key change by an
administrator. |
| $adeleted |
Entire HTML screen displayed after a successful record deletion by an
administrator. |
| $tips |
Instructions for the data entry screen. This is not strictly required,
but the default instructions are decreasingly useful. |
Miscellaneous
- $fext
- Filename extension for created HTML files, default html.
- $suppressPasswords [sic]
- Define this iff you are not using built-in authentication.
- $disallowDelete
- Define this iff you wish to disallow data providers from deleting
their own entries.
- $log
- Define the name of a file to receive a log of each action. Such a
log contains all the posted data, and could in theory be used to recreate
the entire databank.
- $timeFmt
- Format that all dates/times, which are formatted with
strftime(3), will appear in. The Default is '%A, %B %d, %Y
at %H:%M', which yields strings like "Friday, April 13, 2004 at
14:55".
- $adminPW
- If you are using the built-in authentication for administrators, this
is the encrypted password. You can use htpasswd(8) to generate
it. Required iff you are using built-in administrator auth, which you are
unless you provide at least one value in @admins.
- @admins
- This is a list of user IDs that can access the administrative
screens of the tool. If you provide a value for this, then you must
protect the administrative URL with some kind of external
authentication- basic or CSENetID, perhaps- so that the
REMOTE_USER environment variable has a value.
- $accept
- Label for submit buttons. Default is 'Submit'.
- $extra_header_content
- The contents of this string is added to the <head> of each
page, be it static or dynamic.
- $notes
- Points to an anonymous array of HTML snippets that are appended to
name fields of form elements when they are displayed. For example, a
form element with a value of 1 for its notes field
is displayed with ${$notes}[1] appended.
Form Components: @elements
User entries consist of fields, which typically correspond to form
elements (or sets of form elements). The set of fields is described by
an array of anonymous hashes called @elements.
The first entry in @elements is the key value, which must
be unique across entries.
Below is a description of the fields in the members of
@elements. Unless otherwise specified, the values are
strings and the fields are optional. Except as noted, each corresponds
to a field in the user input form.
- tag
- Internal field name. When the persistant storage is a DBM file,
this is the filename. Required unless the type is static.
- name
- This is what's displayed to the user as a prompt on the input
form, is printed by default to the HTML files, and is displayed by
default on the search form. Required. See dname for information on overriding this value
for the search form and HTML files.
- dname
- If specified, this value is used instead of name on
the search form and in HTML files. On the input form, it is useful to
have the prompt be a question, but that doesn't work as well in the other
contexts.
- type
- The type of the field. Required. Recognized values are:
- text
- A single-line text field.
- static
- Static HTML, not corresponding to a hash or to a field in the input
form. Such entries must not have a tag
field, and must have a scope field.
- userid
- The value of the REMOTE_USER environment variable,
which is set whenever authentication directives are used for
controlling access to the CGI. Computed.
- select
- A picklist. Values are provided in the options field.
- checkboxes
- A set of checkboxes with the same name but unique
values. The values are provided in the values field.
- textarea
- A multi-line text field. The size is set by the rows and cols fields.
- radio
- A set of radio buttons. Values are provided in the
values field.
- radio_array
- A set of sets of radio buttons. They must share common
values. The names are provided in the names field.
- modified_date
- The time at which the record was last modified. Computed.
- creation_date
- The time at which the record was created. Computed.
- auto
- An automatically-generated (integer) key. This comes in
handy where no other field is assured to have unique values
across all entries.
- scope
- This field is only for entries of type static, and specifies the contexts in
which the HTML is printed. Currently, the only supported value is
entry, which means that it only appears in the data input
form.
- immutable
- Displayed in the forms, but not editable by the
users. Boolean. This might be useful when a databank is preloaded
with data in certain fields that should never change.
- size
- For an element of type text, the
size of the form field.
- maxsize
- For an element of type text, the
maximum size of the input data.
- small
- Specifies that the field value should be displayed in a small font.
- required
- If defined, marks the element as requiring that a value be
entered. Form submissions without such a value are rejected.
- default
- Specifies the default value for a text or textarea field. If a reference to a
function, that function returns the value.
- nohtml
- Boolean. If defined, specifies that HTML will not be accepted
in the value. Specifically, < and >
characters will be filtered to < and
>. text or textarea.
- searchable
- Boolean. If defined, specifies that this element can be used to
participate in a search: it will appear in the search form.
- note
- Integer. Specifies the index of the element from the anonymous
array pointed to by $notes that contains text that will be
appended to the name field in the forms.
- bogus
- Boolean. Specifies, in a element with type select, that the first value in the options array is not considered a
valid entry. For a required field, that isn't an acceptable
value. For a search, it means not to filter the records according
to that field.
- options
- Array. Values for a select element.
- values
- Array. Values for radio, radio_array,
- names
- Array. Values radio_array
names.
- tags
- Array. Values for name attributes
of radio_array form elements
are constructed from the tag field for
the element, followed by a |, followed by one of these
values. E.g. grade|cse341.
- hide
- Boolean. If defined, don't display this element in the HTML
files if the user-defined function hide() returns a
non-zero value.
- wrap
- Boolean. If defined for a textarea, include the wrap
attribute with the value physical.
- multiple
- Boolean. If specified for a select, allows multiple values to be
selected.
- valid
- A regular expression that valid values for a text field must match.
- mailto
- Specifies that the value should be wrapped in a mailto
link. Obviously, this is pointless unless it's an email
address. Applies to text fields only.
- url
- Specifies that the value should be used as the anchor for a link.
Applies to text fields only.
Configuration File Code
A small amount of code, in the form of functions, must be provided
in the configuration file. Optional except as indicated.
- pwcheck()
- For build-in auth, implements a policy on password characteristics.
The default policy simply requires four or more characters.
- display(key)
- Used in various contexts to build a one-line identification for an
entry. For example, the submitter's last name, comma, first name.
- createIndex()
- Create the entire index from scratch.
- indexLine(key)
- Used to create a single anchored entry for the index.
- sortfunc(a, b)
- Used to sort entries for the index. Required.
- toFile(key)
- Create an HTML file from a single entry.
Examples
Here are some examples of deployed applications of
form.cgi. (Desparately incomplete.)
- DIAC-2000
E-Resource
- Uses built-in authentication to provide a sort of "guestbook" application
for attendees of the Directions
and Implications of Advanced Computing Symposium, held in Seattle in
May 2000.
[Last modified Saturday, October 25, 2014, at 11:29AM PDT.]