
** 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.

Drawing Figures
===============
- Definition files (def/*.d) MUST be appended with Image.d to allow specific
  processing (the template is not def/autocode.php but autocodeImage.php)
     e.g.:   	  plotMyStuffImage.php
- No changes to the previous file content except for these 4 items:

     1) The 'restrict' keyword should be used in the 'show' column of
     	FIELD entry if displaying the column values is wanted.
	Such FIELDs are used in the WHERE restriction clause, not in
	the query.

	Note for developpers: actually any word different from the
	existing keywords '', 'value', 'none', 'image=xxx',
	'value=xxx' are ok.  No code was developped to support this
	keyword in the scritps/generate script.

     2) 'TOPLOT <list of db columns>': defines the list of columns to
     	query.
	e.g.: 
	      TOPLOT camProcessedExp.fwhm_major
	      TOPLOT chipProcessedImfile.bg, rawExp.sun_angle
	All values (no LIMIT) are written to a temporary (text) file
	of the /tmp directory.
	In a row, the different values are separated by a single space
	(i.e. ' ').

     3) 'PLOTTER <php_script_name>': defines the name of the PHP
        script that will call an external tool (e.g. a DVO script).
	
	It is expected that the PHP script named 'php_script_name'
	supports the following parameters:
	- input: the name of an input text filename;
	- output: the name of an output image filename;
	- title: a string (see item 4) PLOTTITLE).

	e.g.:
		PLOTTER scatterPlot.php	
		PLOTTER plotHistogram.php

	The list of existing plotters are detailed further.

     4) 'PLOTTITLE <A title>': defines the title of a figure. Could be
     	used in the external program which is effectively used for
     	rendering the figure.

	e.g.:
		PLOTTITLE A title

Existing plotting scripts
=========================
raw/skyplot.php (calls scripts/skyplot.dvo)
	Text input file needs to contain 3 columns

raw/plotHistogram.php (calls scripts/build_histogram.dvo)
	Text input file needs to contain 1 column
	Computes the histogram of the input file data for 100 bins.

raw/scatterPlot.php (calls scripts/pot_x_vs_y.dvo)
	Text input file needs to contain 2 columns
	Scatter plot of the first column values vs the second ones
	Regression line is also plotted (correlation coefficient is
	shown in title).

Plotting with PHP and temporary files
=====================================

Plots in PHP use temporary files (to provide data to dvo scripts and
to store result images). Unfortunately, if the files are deleted at
the end of main php script, the browser does not have the time to
render the image. If the file is not deleted, they remain in the /tmp
directory leading to disk space exhaustion.

To avoid this problem, the function delete_old_tmp_files() in ipp.php
was created. It checks the /tmp directory and removes all files
belonging to the $DELETION_USER user and that are older than
$DELETION_DELAY minutes. delete_old_tmp_files() is called at the
beginning of the autocodeImage.php template script (line 4) and is
therefore present in all generated plotting scripts.

$DELETION_USER and $DELETION_DELAY are defined in site.php.in (values
are 'apache' and '15').
