WDB - Syntax of Form Definition Files

General file format

Form definition files (.fdf's) are basically just a set of attribute definitions. First a set of attributes for the form as a whole is defined, then a set of attributes for each field in the form are defined.

All attribute definitions are of the form :

               Attribute = value

Blank lines and all characters after a '#' are ignored. It is important that there are no whitespace before the attribute name. Lines beginning with white-space are considered continuation lines of the previous attribute definition.
Leading and trailing whitespace are removed from the attribute values.

Form attributes

All form attributes are always before any field definitions in the file, and always in CAPITAL letters.

In the following a (R) means that the attribute is required, and a (E) means that the attribute values is evaluated by a perl eval command. Remember to quote strings in attribute values that are evaluated.

NAME: Name of this form. Typically the same as the filename without the .fdf extension. This field is optional but should be included for documentation purposes. It could also be used for reference in url attributes.
TABLE (R): List of tables to query. Use commas as separator if more than one table is needed. ( Used directly in a Sybase from clause. )
DATABASE (R): Name of the database to use ( for a Sybase use statement ).
TITLE (R): Text for the <TITLE> tag in the query form and the result page.
Q_HEADER: Text for the first <H1> tag in the query form.
R_HEADER: Text for the first <H1> tag in the result page.
D_HEADER: Text for the first <H1> tag in the result of a default query page.
DOCURL: A url pointing to the documentation for the current form. This url is Automatically added to the Q_HEADER and the R_HEADER texts.
Q_HTML: Extra HTML text to add to the query form.
R_HTML: Extra HTML text to add to the result page.
D_HTML: Extra HTML text to add to the result page of a default query.
RECTOP (E): <H2> tag to add as a header to a record in full-screen output mode.
CONSTRAINTS: Extra query constraints added to the where clause in the select.
JOIN: If more than one table is specified, join conditions must be specified here. (Use the ENTITY names given in the field definitions)
ORDER: column(s) to order by.
PERL (E): Extra perl statements that should be interpreted when the form is read. This is typically used to define functions etc, used later in some of the attributes like from_db and to_db.
COMMENTS_TO: E-mail address of the person to send comments to regarding this form. This will show up at the end of each page, with a link to a page from which the user can send comments via e-mail to the person mentioned.

Field Attributes

Field attributes always appears after all form attributes in the file. The 'FIELD' attribute should always be the first attribute for a field. All attributes defined after this will belong to that field, until the next 'FIELD' attribute is met.

In the following a (R) means that the attribute is required, and an (E) means that the attribute value is evaluated by a perl eval command. Remember to quote strings in attribute values that are evaluated !

FIELD (R): Field identifier. Used internally to uniquely identify a field.
label: Label/title in forms etc. Defaults to the value of FIELD
column: Database column definition. Defaults to the value of FIELD. column values can include Sybase computed fields, and table-names. If more table names are used in a form, remember to mention all tables in the TABLE attribute, and join conditions in the JOIN attribute.
type (R): Database type of field [ int | char | datetime ]. This is currently only used in the construction for the query, to decide whether or not to put quotes around the values, and whether or not the LIKE operator can be used.
unitlabel: Unit label to add at the end of the query fields / result values.
help (E): A url to a some help about the content of the current field. If this field starts with a # sign, the value of DOCURL will be prepended to the url.
length (R): Length of field including formating etc.
key: If set, this is a key field. Key fields are needed to make direct references to a specific row in the database via a URL. More than one key field can be specified. If this is the case the keys listed in the URL attribute should be given in the same order as they appear in the fdf file. ( No value is needed for this attribute. )
url (E): URL link to add to field when displaying results. Embedded perl expressions are evaluated before the url are added to the field. A typical example is adding a url to the key field pointing to it self. In this way the user can click on a row in tabular output and see the full screen representation of the row. Here are an example with two keys ( When more than one key is specified they should be separated by double colon (::) ) : url=$WDB/$form{'NAME'}/query/$val{'keyfield1'}::$val{'keyfield2'} Please note the use of the $WDB variable instead of the name of the script (http://.../cgi-bin/wdb/). This makes it easier to use more than one version of the wdb script ( for example a development version and an installed version ).
from_db (E): Formating function used when converting data from database format to the format that should be presented to the user. A typical example could be conversion of coordinates from internal database format to hours minutes and seconds, which are presented to the user :
from_db = &ed_pic( $val{'ra'}/150 ,"99 59 59.99");
to_db (E): Formating function to use when converting what the user typed to the the format understood by the database. An example :
to_db = &tr_pic( $val,"99 59 59.99") * 150;
default (E): Default value to insert in the query form input field before presenting it to the user. The user are free to change or remove this value.
enum: Enumerate type. The value of this attribute is a list of the form : "dbval=userval,dbval=userval,..." where dbval are the value in the database and userval are the value as presented to the user. The first value set listed will be the default when the form are displayed to the user. A special dbval of % is interpreted as a match-all value and is not included in the SQL query. An example :
enum = %=ALL,SOFT=Software,DATA=Data,DOC=Documentation
no_query: If set, it will not be possible to query on this field.
no_tab: If set, the field will not appear in tabular output. ( The user can override this for query fields = those without no_query.)
no_full: If set, the field will not appear in the full-screen output. This is typically used when a table has a 'title' field that should appear at the top of the full-screen output as a real title (using the RECTOP form attribute), then the no_full attribute should be used for the field to prevent it from being repeated twice on the screen.
tablen: The field can appear in the tabular output, but will be truncated to the length specified as the value of this attribute.
forcetab: The field will always appear in the tabular output. This is typically used on the key field with the url leading to the current record ( - to allow the user to click on a row in the tabular output and get the full-screen version of the row).
hidden: The field is not displayed. The value can be referenced with the $val{'fieldname'} variable from other fields (computed fields, input converters, url specifications etc.)
computed: The field is computed at runtime. The value of the field must be computed in the from_db attribute. The value of other fields can be accessed with the $val{'fieldname'} variable. Normally the no_query attribute should be set for computed fields.

Internal variables

There are some internal perl variables that can be referenced in the attribute definitions above. Most of them has already been mentioned, but to summarize they are all listed here :

$val{'fieldname'}: Value returned from the database after the query has been performed. This is typically used in from_db and url.
$val: Value of the users input in the current field after special characters (<,>,=) has been removed. This is typically used in to_db.
$form{'form-attribute'}: The value of a form attribute. This is not really needed, unless in order to avoid duplicating things. For example $form{'NAME'} could be used in the url attribute, so if the name of the form is changed only the NAME attribute needs to be changed.
$field{'field-name','attribute-name'}: The value of a field attribute. Not really needed by the form writer.
$WDB: The name of the script used to access this form. This is set by wdb on each invocation. If used in url references it is a lot easier to test different versions of wdb on the same fdf files. This variable should not be changed !
$MAIN_MENU: A URL to the main menu of forms, or the homepage. This URL is used for the 'Home' button.
$QUERY_HELP: A URL to the query help. This URL is used for the 'Help' button.
$NULL_VALUE: The value to display as the NULL value. (default is an empty string "").
$MAXROWCOUNT: The Maximum allowed value for the 'Return max .... rows' field.
$rowcount: The default value for the above field. This controls the maximal number of rows that can be returned from a query.

Functions

These are functions build into WDB - However you can always add your own functions and include them either directly in the fdf file (under the PERL form attribute) or include them in your own Perl package and install it in your Perl library directory - then include them with the Perl 'require' statement in the PERL attribute or in the wdb.conf file to make them available in all your fdf files.

&add_menu( $text, $href, $img )

This function can be used in the PERL form attribute to add extra menu options next to the Submit, Reset, Help, etc. buttons. Either a text or a GIF button can be used. ( See notes on how to create GIF buttons. )

$text: - is the text label to use, either directly or as the ALT attribute if a GIF button is supplied.
$href: - is the URL to execute when the button is pressed.
$img: - is the URL to the GIF file to use as button. If this argument is left out a normal text link is created instead.

&cgi_encode( $str )