Form Specification File

Overview

Like the template data specifications we have seen up to this point, form specifications are also well-formed XML documents. The content of the two is completely different, however. Rather than a list of sources to derive dynamic data, the form specifications describe the properties of each element in a form. Basic properties include:

the type of widget
the type of data to be entered (i.e. text, number, email, url, etc.)
default value(s) to initialize the widget
a list of options to populate button groups and select lists
mappings between the element value(s) and tables and columns in the database

The form specification also contains general properties about the form, including attributes of the form tag itself.

The form specification file is an XML document containing sufficient information to generate a complete form. The file has the following generic structure:

<form>

  General 

General Properties

The general properties apply to the form as a whole
rather than any particular element.  The name
property is used internally to define global variables
for each form element, and optionally by the template
author when referencing these variables.  The type
property is optional and may be used to specify that
the rendered form should be of type multipartdbaction property generally defines the type
of database actions to perform based on the form submission
(updates based on checkbox groups or select multiple widgets may
actually be performed by a delete-insert sequence).  A single
form may require several database statements to process, all of
which are contained in a single transaction.

The optional title and help properties may contain
a title and some explanatory text to place at the head of the form.

Element Properties

Each form specification contains an elements
container, within which is a series of one or more
elements in the order in which they should appear in an
automatically generated form.

Each element possesses a name property, which the
template author uses to identify the element and which is
used to name the element in the rendered form.

The label and help properties contain
text that may be referenced by template authors when laying
out the form template.

The widget property specifies the type of widget
to generate for the element.  Any of the standard form elements
may be used, in addition to custom widgets composed of
combinations of form elements (i.e., the date widget included
with the form manager).  The width attribute is used
to set the SIZE attribute of the INPUT tag,
as well as the COLS attribute of the TEXTAREA
tag.  The height attribute is used to the SIZE
attribute of the SELECT tag, as well as the ROWS
attribute of the TEXTAREA tag.

The options property provides a flexible way to
specify the labels and values for radio and checkbox groups and
select lists.  If the static method is specified, then a
list of items is expected in the following form:

<options method="static">
  <item value="value1">label 1</item>
  <item value="value2">label 2</item>
  <item value="value2">label 3</item>
  ...
</options>


If the query method is specified, then a database query
is expected in the following form (note that the query must rename the first column
label and the second value):

<options method="query">
  select
    col1 as label, col2 as value
  from
    table
  ...
</options>


If the eval method is specified, then Tcl code
is expected which should result in a list of duplets in the form

{ {label1 value1} {label2 value2} ... }

The default property specifies the default values to set
the form element when no other values are currently known (i.e., for a
"new" or "add" type of form, as opposed to an "update" form in which
the user has previously given a value).  The methods are the same as
for the options property, although the format expected for
each is different.  Static defaults should be a single vertical-bar
delimited string (i.e., value1|value2|value3).  The query
method for this property should specify a single column query, and the
eval method should specify code that returns a simple list.

The final section of the element block is zero or more
dbmap properties, which specify how and where the values
obtained from a form element map into the database.  The key
attribute is critical for proper handling of the form submission
(although it may become optional in a future release since the
form manager can actually query for this information from the database
data dictionary tables).
The column
property is optional and needs to be used only when the column name
in the database differs from the name of the form element.

Pre- and post-processing

It is frequently the case that a form submission handler must do
more than just modify some database tables.  Sending mail and setting
cookies are examples of other common actions.  The form specification file
may include preprocess and postprocess blocks that
encapsulate such actions within a structured framework.