
** the current definition files correspond to tasks.md 1.86
** update this file if you need to update the tables

Each of the *.d files in this directory (except example.d) are used to
define a page in the ipp web tools which show the contents of a
database table (or tables).  There are also pages which do not refer
to a specific database table: these are defined in ../raw and are not
pre-processed with the 'generate' function.  The contents of the
description file are confronted with a template file and used to
generate PHP code.  

The layout of each page is essentially the same: the page is divided
into a main data area and a left-hand side navigation table.  The
contents of the navigation table are defined by the menu definition
file specified for the page.  The data area includes the following
elements:

- TITLE
- HEAD (html or php code)
- TABLE
- TAIL (html or php code)

The *.d file defines each of these regions with a set of rules.  Each
rule is specified on a single line, and begins with one of the defined
keywords.  Several keywords are required to be unique (eg, TABLE and
TITLE) while others may be repeated (eg, WHERE, FIELD).  For most of
the keywords, there is no fixed format for the value, but in the case
of the FIELD keyword, care must be taken to follow the mandatory
syntax. 

The TITLE is define by a single, fixed keyword (TITLE).

The HEAD and TAIL regions are defined by the HEAD and TAIL lines, and
are optional.  Each HEAD or TAIL line is followed by a word defining
the code type (may be HTML or PHP).  The rest of the line defines code
which is interpreted as either HTML or PHP.  These replace the lines
"// ** HEAD CODE **" and "// ** TAIL CODE **" in the template file.

By default, the menu definition file for the page is defined by the
specified MENU key.  If, however, the page is passed a "menu=XXXX"
directive (either via GET or POST), then the specified file is used
instead as a menu definition file.  This mechanism is used to allow
the same table definition page to be linked from different locations
in the pages and have the same appearence as the referencing page.

The rest of the file defines the displayed contents of the table.  The
page generates an HTML table based on a query of one (or possibly more
than one, see below) database tables.  The table used for the query is
specified by the TABLE key.  An SQL command is generated based on the
requested fields, defined by the FIELD keys.  If desired, WHERE
statements may be added to the SQL command with the WHERE key.  Each
line marked by WHERE is appended (with AND) to the SQL WHERE clause.  

The FIELDS lines define both the queried fields and the rules for
presenting the fields in the HTML table.  Each FIELD row results in a
column in the output HTML table, unless otherwise noted (see below).
Each FIELD row also corresponds to a queried field from the database
table, again unless otherwise noted.  Each FIELD command is followed
by a set of comma-separated values.  The first entry defines the name
of the database table field.  The second entry defines the minimum
width of the column.  The third entry defines the column header.  The
rest of the entries are optional.  The fourth entry specifies what is
placed in the cell, and may consist of:

- the string "value", in which case the corresponding data entry from
the database for the column and row are used to fill the cell.  This
is the default behavior.

- the string "value=XXX", in which case the cell is filled with the
value of XXX instead of the corresponding database cell value.  If XXX
consists of one of the specified database fields, that column's data
for this row is substituted instead.  

- the string "image=XXX", in which case the cell is filled with the
image represented by the URI XXX.  

- the string "none", in which case the cell is column in the output
HTML table.  Such elements are needed to lookup a value from the
database (ie, to be passed to links, see below) but not to display the
value in the table.

The fifth entry defines an optional link for the cell.  If this field
is set, a link is created for the cell using the given word as the
target of the link.  The link will also have the mandatory GET data
attached (including the menu and the pass data needed to validate the
user).  

The sixth entry is used to specify additional information passed to
the linked page via GET data elements.  These are typically of the
form "word=value", and may include multiple comma separated
entries. If the value elements consist of $field where field is one of
the valid database field names, this value for the current row is
passed with the link.

If the first entry of the FIELD row has the value "*", then the row
is NOT used to define a database field; it is only used to define an
output column in the HTML table.

