Home | About | Documentation | Download

Next: How to use WDB Up: WDB Installation and Users Previous: Writing Form Definition Files

Form Definition File Syntax

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 are defined, then a set of attributes for each field in the form. 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 an (R) means that the attribute is required, and an (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 SQL from clause. )

DATABASE (R)

Name of the database to use.

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 as a hypertext link to the Q_HEADER and the R_HEADER texts.

Q_HTML

Extra HTML text to add to the query form just below the header.

R_HTML

Extra HTML text to add to the result page just below the header.

D_HTML

Extra HTML text to add to the result page of a default query just below the header.

RECTOP (E)

<H2> tag to add as a header to a record in full-screen output mode. Typically the title of the row. For example in a FDF that queries persons you might want a RECTOP like this :

    RECTOP = "$val{'last_name'}, $val{'first_name'}";

CONSTRAINTS

Extra query constraints added to the where clause in the SQL select statment.

JOIN

If more than one table is specified, join conditions must be specified here. (Use the column names given in the field definitions)

ORDER

Column(s) to order by. If more than one column is given, seperate by commas. (Used directly in a SQL select order by ... clause)

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. ( See also the html_tail definition in the wdb.conf file )

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 an (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. Depending on your database, column values can include computed fields, and table-names etc.İf 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 of 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 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. This is added as a hypertext link to the field label in the query form.

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 is 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 formatting a number with proper precision etc..

     
    from_db = sprintf("%8.2f", $val{'salary'} );

to_db (E)

Formating function to use when converting what the user typed to the the format understood by the database.

default (E)

Default value to insert in the query forms 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 is the value in the database and userval is 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

multiple

Allows the user to query on multiple values in an enum field (default is to allow only one value). Multiple values are or'ed together in the query.

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, i.e., 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

This is not a database field, but 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. However it is possible to allow the user to query on a computed field, and then use the entered value to affect the queries on other, possibly hidden, fields. If you want to do that you have to write a function to parse the users typed in value, and insert it in the to_db attribute of the computed field. To modify the query on another field, set the $in{'field-name'} variable.

sameline

If set the field will apear on the same line as the previous field in the query form and the full-screen output.

html

The value of this attribute is inserted as HTML text on the line before the current field in the query form and the full-screen output.

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 maximum 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 as well 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 appendix 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 )

Encodes a string so it doesn't cause problems in a URL. If you have a keyvalue that could contain special characters like spaces, % signs etc. you can't just included it in a normal url like :

    url = "$WDB/$form{'DATABASE'}/$form{'NAME'}/query/$val{'keyfield'}"

In this case you would have to encode the key value using cgi_encode like this :

    url = "$WDB/$form{'DATABASE'}/$form{'NAME'}/query/" . &cgi_encode($val{'keyfield'})

Next: How to use WDB Up: WDB Installation and Users Previous: Writing Form Definition Files

Latest News
New Homepage! 24-Feb-2000 SourceForge Hosting 5-Mar-2000

Downloads

WDB Ver.1.4
6-Mar-1996

WDB Ver.2.000 beta
24-Feb-2000