\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}