NAME 

        Interface Builder -- Data-driven HTML table-based form builder

DESCRIPTION

NOTE: this file is not 100% up-to-date at this time and it's contents are still subject to change. The the interfaces are offically made public this document will be updated.

Generates HTML forms based on an input file that describes the elements of the form.

The default table is four columns wide and is filled in row-major order.

If you wish you build your own interface inside the standard table you can build a single Literal input record and put whatever you wish inside of it.

Data File Syntax

The data file is a collection of records, each seperated by one or more blank lines. Each entry in a record is a ``keyword: value'' pair. The recognized ``keywords'' are defined below.

Spaces and tabs after the colon (``:'') that terminates a keyword, upto the first newline, are ignored. Comment lines begin with a pound sign (``#'') and are ignored (and they do not count as blank lines seperating records either).

The `value' portion of an entry may be continued on extra lines by begining the lines with white space (which is removed): 

    Long-Input:   This is a very long input field.
                  which has continuation lines.

or by an initial greater-than (``>'') [possibly preceded by white space] which allows you to have input lines with leading white space: 

    Long-Input:   Another long input field with
                  continuation lines.
                 >    But this line contains leading
                  white space that has been escaped with a
                 >>.  Only B<leading> greater-than (``>'')
                  signs need to be escaped.

An initial greater-than can be used to escape the meaning of any special characters (initial greater-than's, open brackets (``[''), open curly braces (``{''), and comments (``#'')): 

    Literal:     >{this_is_a_literal_not_code}
                 # this is a comment and is ignored
    Literal:     >more literal text
                 ># this is literal text also, not a comment
                 >   This is a line with some leading white space.

There are three types of values: Literal, List, and Code.

Literal
Anything that does not begin with an open bracket (``['') or open curly brace (``{''): 

    Name:       thing

To generate Literals with a leading {'s or ['s you can use the greater-than (``>'') escape: 

    Name:      >{thing}

List
Specified inside of brackets (``[...]'') and is implemented as perl5 style ARRAY REF's which are eval'ed inside of perl so all the perl quoting rules apply: 

    Actions:   [ 'Create', 'Test' ]

You can even embed perl code in the expression: 

    Actions:   [ @actions ]

Code
Specified inside of curly braces (``{...}'') and is otherwise treated the same as a List. 

    Actions:   { ['Create', 'Test']; }

or 

    Actions:   { function_returning_an_array_ref_of_actions(); }

List and Code evaluations are done in the package specified in the View meta record for the ``Package'' keyword, if not specified it defaults to ``main''. It is generally recommend that you keep actual code in the datafile a minimum. You can alway put support routines in Initialize.pm and just call them. The initial parsing of List and Code entries is the same as for Literals.

Data Driven Input Types

Each input type lists the fields it defines, the datatype of the field (String, Array, Hash); whether it is required or optional; and the default value, if any.

The field datatypes are: String, Array, and Hash.

Strings can be input as either a Literal, List (the elements of list will be joined together with spaces), or Code (which can return an ordinary perl scalar or an ARRAY REF).

Arrays can be input as either a Literal (interpreted as an array with only one element), Array, or Code (which must return a perl ARRAY REF [e.g., ``{ my @list = (``one'', ``two''); \@list ; }'' or more simply ``{ [``one'', ``two'']; }'']).

Hashes (an array indexed by a string instead of a number, aka an associative array) can be input as either an List or Code (which must return a perl HASH REF or ARRAY REF): 

    Hash:       [ 'keyword', 'value' ]
    Hash:       { {'keyword' => 'value'}; }
    Hash:       { \%somehash; }
    Hash:       { function_returning_hash_ref(); }

A Literal value is not meaningful in this context.

In all cases, if the ``Label'' keyword is present an extra element of type ``Header'' is generated first.

View
Meta Information about the current View. Used to fill in various parts of the interface. 

    Package     -- String.  Optional.  Default: main
                   Name of package (e.g., SysAdmin::Accounts::Create)
                   used for all perl code eval's.
    Initialize  -- String.  Optional.
                   A place to put an initialization code eval
                   (e.g., { require Application::Module; }).
                   The value is not used except for it's side effects.
    TitleBar    -- String.  Required.
                   String to be used for the &lt;TITLE&gt;
    Header      -- String.  Required.
                   String to be used in the first &lt;H1&gt; header.
    HeaderNote  -- String.  Optional.
                   Extra information under header.
    Dynamic     -- String.  Optional.
                   Indicates that the browser should always reload this
                   page if the string is affirmative (Enabled).
    Actions     -- Array.  Required.
                   List of actions valid for this interface.
                   They are used to build the submit buttons.
                   I<Reset> is added automatically.
    Trailer     -- String.  Optional.
                   An HTML trailer, used to add any extra markup,
                   like hypertext links and copyrights, to
                   to the end of the interface.  It is placed
                   outside the &lt;TABLE&gt; but still inside the FORM.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Header
Table header/label. 

    Label       -- String.  Required.
                   Header label.

Text
Normal text input field. 

    Label       -- String.  Optional.
                   Header label.
    Name        -- String.  Required.
                   HTML &lt;INPUT&gt; tag name.
    Size        -- String.  Optional.
                   HTML &lt;INPUT&gt; field size.
    Value       -- String.  Optional.
                   Default value for field.
    MaxLength   -- String.  Optional.
                   Maximum input length for field.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Password
Just like Text but doesn't echo what is typed. 

    Label       -- String.  Optional.
                   Header label.
    Name        -- String.  Required.
                   HTML &lt;INPUT&gt; tag name.
    Size        -- String.  Optional.
                   HTML &lt;INPUT&gt; field size.
    Value       -- String.  Optional.
                   Default value for field.
    MaxLength   -- String.  Optional.
                   Maximum input length for field.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Hidden
Form data for maintaining state. This does not generate a table entry. 

    Name        -- String.  Required.
                   HTML &lt;INPUT&gt; tag name.
    Value       -- String.  Optional.
                   Default value for field.

Select
Scrolled selection list (1 of N). 

    Label       -- String.  Optional.
                   Header label.
    Name        -- String.  Required.
                   HTML &lt;SELECT&gt; tag name.
    Size        -- String.  Optional.
                   HTML &lt;SELECT&gt; size.
    List        -- Array.  Required.
                   List of options to select from.
    Selected    -- String. Optional.
                   Item from List that is initially selected.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Select_Multi
Scrolled selection list (N of N). 

    Label       -- String.  Optional.
                   Header label.
    Name        -- String.  Required.
                   HTML &lt;SELECT&gt; tag name.
    Size        -- String.  Optional.
                   HTML &lt;SELECT&gt; size.
    List        -- Array.  Required.
                   List of options to select from.
    Selected    -- Array. Optional.
                   Items from List that are initially selected.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Select_Popup
Popup-style 1 of N selection. 

    Label       -- String.  Optional.
                   Header label.
    Name        -- String.  Required.
                   HTML &lt;SELECT&gt; tag name.
    List        -- Array.  Required.
                   List of options to select from.
    Selected    -- String. Optional.
                   Item from List that is initially selected.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Select_Radio
Radio button selection list (1 of N). The elements of List are formatted into a Fill table of Columns columns. If an element of List is in the perl HASH table Links an HTML anchor is generated with the URL from the HASH table. All elements in List that match elements in Checked are checked. 

    Label       -- String.  Optional.
                   Header label.
    Name        -- String.  Required.
                   HTML &lt;INPUT&gt; tag name.
    Fill        -- String.  Optional.  Default: Column-Major
                   Fill style, one of: Row-Major, Column-Major
                   XXX: only Column-Major is currently supported
    Columns     -- String.  Required.
                   Number of table columns to use.
    List        -- Array.  Required.
                   List of options to select from.
    Links       -- Hash.  Optional.
                   Hash of list option to URL.  Used to make
                   hypertext links out of the table elements.
    Checked     -- String.  Optional.
                   Option selected by default.  This is a single
                   string unlike Select_Checkbox where you can
                   have multiple entries checked.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Select_Checkbox
Checkbox selection list (N of N). The elements of List are formatted into a Fill table of Columns columns. If an element of List is in the perl HASH table Links an HTML anchor is generated with the URL from the HASH table. All elements in List that match elements in Checked are checked. 

    Label       -- String.  Optional.
                   Header label.
    Name        -- String.  Required.
                   HTML &lt;INPUT&gt; tag name.
    Fill        -- String.  Optional.  Default: Column-Major
                   Fill style, one of: Row-Major, Column-Major
                   XXX: only Column-Major is currently supported
    Columns     -- String.  Required.
                   Number of table columns to use.
    List        -- Array.  Required.
                   List of options to select from.
    Links       -- Hash.  Optional.
                   Hash of list option to URL.  Used to make
                   hypertext links out of the table elements.
    Checked     -- Array.  Optional.
                   List of options selected by default.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Select_Input
Popup-style 1 of N selection plus a text input field. 

    Label       -- String.  Optional.
                   Header label.
    Select_Name -- String.  Required.
                   HTML &lt;SELECT&gt; tag name.
    Select_List -- Array.  Required.
                   List of options to select from.
    Select_Selected     -- String.  Optional.
                   The item from Select_List that is to be initially selected.
    Input_Label -- String. Optional.
                   Text label for input box.
    Input_Name  -- String.  Required.
                   HTML &lt;INPUT&gt; tag name.
    Input_Size  -- String.  Optional.
                   HTML &lt;INPUT&gt; field size.
    Input_Value -- String.  Optional.
                   Default value for field.
    Input_MaxLength     -- String.  Optional.
                   Maximum input length for field.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Span
A spanning subtable to allow more powerful formatting options. Spanning tables, like the outer table, are filled in row-major order. 

    Rowspan     -- String.  Optional.  Default: 1
                   Number of rows to span.
                   XXX: A value of 1 is all that is currently supported
    Colspan     -- String.  Optional.  Default: 1
                   Number of columns to span.
                   XXX: A value of 4 is all that is currently supported
    Elements    -- String.  Required unless Literal is used.
                   Number of input elements to read.
    Columns     -- String.  Required unless Literal is used.
                   Number of table columns to use in sub-table.
    Literal     -- String.  Optional.
                   If used, will place Literal HTML inside the
                   sub-table.

Empty
An empty table field (used to fill in holes in the table). 

    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

Literal
Literal HTML text. 

    Label       -- String.  Optional.
                   Header label.
    Markup      -- String.  Required.
                   Literal HTML Markup to use.
    Help        -- String.  Optional.
                   HTML help text to be used when building
                   the help screen.

HISTORY 

        Early Prototyping, November 1995, BSDI.
        Conversion to Data-driven model, March 1996, BSDI.
        Currently under development.

COPYRIGHT 

        Copyright 1995, 1996 Berkeley Software Design, Inc.
        http://www.bsdi.com/