\documentstyle[guidemacros,psbox,tgrind]{report}
\stdsizes
%include the below line for tty output:
%\addtolength{\textwidth}{-2in}

%\newcommand{\draft}[1]{{\huge #1}}

\title{A form and routing description language for Iris}
\author{Andy Oakland}
\date{\today}
\maketitle

\begin{document}

\section{Introduction}
The description of an electronic form, as used in Iris, has two components.
The first part defines the form's screen appearance; that is, where
text appears on the screen, what types of data are expected for each
input field, and so forth.  The second part of a form description defines
the route along which the form will travel as it moves through the
different phases of its lifecycle.

%As an early step in the creation of an electronic forms-routing system at MIT,
%I have created the following forms description languge.  This language
%will be used to define the screen appearance of a form, and will be
%generated by a forms-design tool (or an incredibly masochistic human!)
%stored in the forms database, and displayed on a screen to be filled out.

Note that the language does not make any reference 
to a particular type of display.  This is deliberate, so that forms
can be displayed on a variety of devices, ranging from simple character-
based terminals such as a VT100 to color X displays.  We expect that the
form descriptions
will be generic enough so that, as new display devices are added, the
existing form descriptions can continue to be used.

It is intended that forms
will appear as similar as possible when they appear on different display
devices...In particular, they will not attempt to reconfigure themselves
to take advantage of different screen orientations and sizes.  If a user
used to filling in a form on one particular display type were to find that
the same form looked different on a different display, he might
be confused as whether it were in fact the same form.\footnote{Furthermore,
repetitive form-filling quickly trains the fingers to move in certain
patterns to fill in the form, with the expectation that the same fields
will always appear in the same location.  Reconfiguring the screen layout
will defeat this "muscle memory."}

\section{Description of the FDL}
The Form Description Language, or FDL, is the mechanism used to define
a form's appearance on the screen.  It allows the used to specify what
types of input fields appear on the screen, as well various attributes
of the fields, such as default values and accompanying text.  A sample
form description is listed in Appendix 1.

A form is defined as a set of fields, where a field can be either an
input field or a display field.  Input fields contain values which the
user can manipulate, while display fields are for non-accessible screen
decorations or non-editable text.

To support low-end devices, such as the afore-mentioned VT100,
the form description language uses hard-coded row and column positions
for the fields.  On a display with variable-size text, these values will
be multiplied by the heights and widths of the largest characters in the
character set.

A form description begins with an open brace immediately followed by
the keyword Form, with the form's name given on the next line in
the format FORMNAME: whatever-the-name-is.

This is followed by a series of fields, and a closing brace once the
list of fields is completed.  A field is composed of an open brace
followed by the keyword Field, to mark the
beginning of a structure; a series of name and value pairs
describing the contents of the structure,
where a value can be a nested structure; and finally a close-brace to
indicate the end of the structure.
\subsection{Definition of a generic field}
A field is defined by a set of name/value pairs, which I have nicknamed
"slots."  All fields contain the following slots.  No slots are mandatory;
all will be given sensible default values (typically NULL or 0)
if the form description does not specify a value.  Of course, too
many missing values will produce an empty or nonsensical field.
In addition, specific subclasses of fields contain further information,
which will be described later.
All fields contain the following generic information:

\begin{tabular} {| l | l|} \hline
NAME&
The name to be used when other fields refer to\\
&
this field for keyboard traversal or value checking. \\ \hline
ROW, COL&
Where the upper-left corner of the field will appear on the screen, as \\
&
measured from the upper-left corner of the display. \\ \hline
SCREEN&
If the form covers multiple screens, this is the (zero-based) index of \\
&
which screen the field will appear on. \\ \hline
TEXTATTRS&
Attributes used by the text in the field, such as boldface or italic. \\
&
[NB  Need to be specific about format here.] \\ \hline
UP, DOWN,&
Names of fields above, below, and to the right and left, \\
RIGHT, LEFT&
for keyboard traversal. \\ \hline
HELPTEXT&
Text to be displayed if help is requested on this field.  Note that it \\
&
is possible to request help on both input and display fields. \\ \hline
HIDDENIF,&
A C-style mathematical expression which determines if the field is\\
REQUIREDIF&
hidden, locked, or required at a given time. \\
LOCKEDIF&
[NB:  REQUIREDIF isn't yet implemented.]  \\ \hline
DETAIL&
A pointer to a structure containing specific information for different  \\
&
classes of fields.  The value of this field is a nested structure, \\
&
beginning with an open brace and either of the keywords "InputField"\\
&
or "DisplayField," followed by a list of name-value pairs and\\
&
terminated by a closing brace. \\
&
[NB:  Should put this in a full description below.]  \\ \hline
\end{tabular}

The expressions used in the HIDDENIF, LOCKEDIF, and REQUIREDIF slots
can refer to the values of other fields by using the fields' names, 
and to the current node number with the variable "nodenumber."  
The value of a NumericInput field is the number it contains, whether
an int or a float.  An exclusive SelectionInput field's value is
the zero-based index of the current selection, and the value of a
BooleanInput field is 1 or 0.
Taking the value of a TextInput or {\it non}-exclusive SelectionInput
field is undefined.

As an example, a field could lock itself
for all nodes except node 5 with the line,

\begin{tt}
\begin{flushleft}
LOCKEDIF:	nodenumber != 5
\end{flushleft}
\end{tt}

and make itself appear and be required if the sum of the fields titled
"total" and "tax" were above 500 with the pair,

\begin{tt}
\begin{flushleft}
HIDDENIF:	total + tax < 500\\
REQUIREDIF:	total + tax >= 500\\
\end{flushleft}
\end{tt}

\subsection{Slots within an input field}
The following slots are used within all types of input fields.

\begin{tabular} {| l | l|} \hline
PROMPT&
A piece of text which is displayed to the left of the actual input \\
&
object.  If you want to display the text to the right of the \\
&
input object, you can specify a negative value for "distance." \\ \hline
DISTANCE &
The distance, in characters, between the left-most edge of the prompt \\
&
and the left-most edge of the input object. \\ \hline
INPUTSOURCE &
A structure containing specific information for each \\
&
type of input object. \\ \hline
\end {tabular}

The value of this field is a nested structure, beginning with
an open brace and one of the keywords "TextInput," "NumericInput,"
"SelectionInput," or "BooleanInput," followed by a list of name-value
pairs and terminated by a closing brace.
It is expected that more values will be made available in the future, as
different sorts of input fields such as lists and sliders are added.

Each type of input object contains different specific information.
A text input field has five slots:  (N.B.:  HEIGHT, VISIBLELENGTH,
and VISIBLEHEIGHT aren't yet implemented)

\begin{tabular} {| l | l|} \hline
LENGTH, HEIGHT &
The maximum allowed length and height, in characters, of the field. \\ \hline
VISIBLELENGTH &
The size of the visible portion of the text field.  If these values \\
VISIBLEHEIGHT &
are smaller than LENGTH and HEIGHT, the text can be scrolled within \\
&
the window to make all parts accessible. \\ \hline
DEFAULTVALUE &
The default value assigned to the field and displayed when the form \\
&
first appears. \\ \hline
\end {tabular}

A numeric input has only one slot:

\begin{tabular} {| l | l|} \hline
DEFAULTVALUE &
The default value assigned to the field and displayed when the form \\
&
first appears. \\ \hline
\end {tabular}

A selection field has several slots:

\begin{tabular} {| l | l|} \hline
CHOICES &
A comma-separated list of possible values for this field. \\ \hline
COLUMNS &
The number of columns in which the choices should be displayed.  A very \\
&
large number will force a single-row horizontal layout, while "1" will \\
&
create a single column.  Small integers will create rectangular layouts. \\ \hline
TYPE &
Either "exclusive" or "nonexclusive." [N.B.  "nonexclusive" is only \\
&
partially implemented.] \\ \hline
DEFAULTVALUE &
The zero-based index of the choice initially highlighted when the field \\
&
appears.  If none is specified, the first choice will be highlighted for\\
&
exclusive types, and nothing will be highlighted for nonexclusives. \\ \hline
\end {tabular}

\subsection{Slots within a display field}
The following slot is used within all types of display fields.
[N.B.  Only "TextDisplay" is currently implemented, and it only works
with single lines of text.]\

\begin{tabular} {| l | l|} \hline
DISPLAY &
A structure containing specific information for each \\
&
type of display object. \\ \hline
\end {tabular}

The value of the DISPLAY slot is a nested structure,
beginning with an open brace and one of the keywords 
"TextDisplay," "BoxDisplay," or "LineDisplay,"
followed by a list of name-value pairs and terminated by a closing brace.
It is expected that more values will be made available in the future.
For example, a "message window" has been suggested, in which the system
can display warning or help messages.

A text display field displays a block of text on the screen.  It
has only one slot:

\begin{tabular} {| l | l|} \hline
DATA &
The string to be displayed on the screen. \\ \hline
\end {tabular}

A line display field produces a horizontal or vertical line on the screen.  
It has two slots:

\begin{tabular} {| l | l|} \hline
LENGTH &
The length, in characters, of the line to be displayed. \\ \hline
ORIENTATION &
Either horizontal or vertical. \\ \hline
\end {tabular}

A box display field draws a box on the screen.  It has two slots:

\begin{tabular} {| l | l|} \hline
HEIGHT, WIDTH &
The height and width of the box to be displayed, including the \\
&
thickness of the lines. \\ \hline
\end {tabular}

\subsection{Future expansion}
This description language is designed to easily allow the addition of new
slots within existing fields, and the addition of new field types.  Some
likely new field types have been mentioned above, including slider
and list input fields, and message display fields.  While allowing this
flexibility, though, I have also tried to give the language enough
meaning to make it immediately useful in the prototyping of an
electronic forms routing package.
\section{Description of the RDL}
While a form sitting in one spot is useful, forms which can
move from one place to another are more useful.
If a form can be imagined to be a railroad car, the route of a form is akin 
to the collection of all the possible ``tracks'' on which this type of
form can travel.  Because the route may have forks in it, the paths
taken by individual forms of the same type may differ.
The Routing Description Language, or RDL, provides the mechanism for
describing a route that each type of form should travel.

A route is defined as a collection of nodes, where each node represents
a different phase of the form's lifecycle.  As defined in Iris' RDL,
each node contains the following information:

\begin{tabular} {| l | l|} \hline
NODENUMBER &
A small integer, used internally to specify which nodes are connected \\
&
to other nodes. \\ \hline
STATUSSTRING &
A string, such as "Pending Approval," which indicates to the user what \\
&
phase of the form's lifecycle the form is in. \\ \hline
ACTIONLIST &
A comma-separated list of string and nodenumber pairs, such as \\
&
\begin{tt}
"{"Approve", 2}, {"Reject", 3}."
\end{tt}
These specify the user-selectable \\
&
dispatch options ("buttons") which will appear at the bottom of the \\
&
screen when the form is at this node.  The nodenumber associated with \\
&
each button specifies which node the form will be moved to if the user \\
&
presses this button. \\ \hline
DEFAULTQUEUE &
This is the person or group to whom forms entering this node should \\
&
be assigned. \\ \hline
\end {tabular}

It is not required that forms move through nodes in strictly ascending order
of nodenumbers; in fact, some amount of looping back or skipping of nodes
is expected for anything but trivial routes.  A form will always begin at
the first node in the list of nodes, and any movement after that is
under the user's control.
\section{Example}
We include below an example of a form defined using this FDL and RDL:
\newpage
\begin{center}
Example of Form and Route description language
\end{center}
\tgrindfile{appendix1.tex}
\newpage
\begin{center}
Graphic representation of route
\end{center}
\PSbox{/afs/athena.mit.edu/astaff/project/forms/doc/example1.ps}{6.0in}{5.0in}
\end{document}

