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

QEVL_HTML

Same as Q_HTML, just it is an evaluated piece of PERL code, which gets executed at run time if Q_HTML is not defined.

R_HTML

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

REVL_HTML

Same as R_HTML, just it is an evaluated piece of PERL code, which gets executed at run time if R_HTML is not defined.

D_HTML

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

DEVL_HTML

Same as D_HTML, just it is an evaluated piece of PERL code, which gets executed at run time if D_HTML is not defined.

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 )

REDUNDANT_FIELDS

A blank separated list of Label=fieldname expressions used to group together and show at the top of the resulting page all the attributes which are common to all following records (very similarly ot the PARAM definition in a VOTABLE). Example: All the members of an association have same assocition id, and might have same filter, roll angle, etc. Those fields are constant for the given association, hence they can be shown once, and not repeteadly in the table showing all the members. The FDF developer has to make sure that the FDF using this feature is invoked (queried) properly; there is no way for WDB to check whether the redundant fields are really constant for the set of returned records.

OPT_CONSTR_URL

URL for the documentation of the selectable optional constrinats (See the opt_constr field attribute below).

DEFINE_NEW_QUERY_OFF

With the form header line: DEFINE_NEW_QUERY_OFF = 1 the "Define new query" button is not displayed. Useful for example for those FDFs which are supposed to be used only as links from the results of some other FDFs. For example, an FDF using the REDUNDANT_FIELD option is likely to use DEFINE_NEW_QUERY_OFF = 1.

NO_DATA_RETURNED

NO_DATA_RETURNED = an html message where the html message is displayed in case of query returning no data.

RECORDS_IN_TABLE

A form attribute to control output table length. E.g. RECORDS_IN_TABLE = 30 will override the default 10 records per output table.

Q_FOOTER

The Q_FOOTER is an html footer to be displayed at the bottom of the input form. (Cfr R_FOOTER)

R_FOOTER

The R_FOOTER is an html footer to be displayed at the bottom of the resulting output page.

REVL_FOOTER

Asme as R_FOOTER just it is an evaluated piece of PERL code, which gets executed at run time.
R_FOOTER and REVL_FOOTER are not mutually exclusive.

ISOLATION_LEVEL

This form attribute can be used to change the isolation level ot the performed SQL. Defaulted to "at isolation read committed", it can be set to a null value by defining it in the form without assignment (no '=' sign).

USER, SERVER, EVL_USER, EVL_SERVER

These form attribute are used to control the access to the database server. Password is retrieved internally using the DBRC mechanism.
EVL_USER and EVL_SERVER have precedence over the USER, SERVER form attributes.
Cfr OPSWAWARE just below.

OPSWAWARE

If set to a non-zero value, the OPSW_DOMAIN and OPSW_LEVEL environment variables will be used to set the SERVER form variable.
It takes precedence over the SERVER and EVL_SERVER attributes.

MD_USER, MD_SERVER, EVL_MD_USER, EVL_MD_SERVER

Controlling access to the Metadata Database. The evaluated attrbiutes take precedence.
Used only if MDAWARE is set to a non-zero value.

MDAWARE

Used to activate the ability to return a VOTABLE, instead of the default HTML page. If is set to not zero, this parameter informs WDB that more metadata (units, UCDs, utypes, datatypes, description, etc.) for the form fields is available either in the Metadata Database, or in the FDF itself, via some vo specific field attributes (See the Virtual Observatory support section below).

CHARSET

The returned HTML page will make use of the META HTML tag to specify a given CHARSET as in:

<META http-equiv="Content-Type" content="text/html; charset=$form{'CHARSET'}">

FILE_UPLOAD

An input file can be uploaded to wdb to perform multiple queries at once, e.g. the same query for any target in a user provided list. For each line in the uploaded file wdb will perform a query, using the regular fdf user's input as contrains. Before parsing the FDF, wdb will override the content of the %in hash key corresponding to the FILE_UPLOAD field.

The FILE_UPLOAD value must be the name of a valid FIELD in the FDF. Example:

     ...
     FILE_UPLOAD = object
     ...
    
     FIELD = object
     ...
    

Each record in the uploaded file will end up filling $in{'object'} before the FDF gets parsed to build the select statement. If, for example, the to_db section of the object field contains a call to SIMBAD, that will be executed for each input object in the uploaded file.
The uploaded file might contain user's comments:

• Lines starting with a single # character will be shown in the resulting output as comments;
• Lines starting with a double # character will not be shown at all, nor made use of.

A multipart/form-data ENCTYPE is used when the file upload option ($form{'FILE_UPLOAD'}) is activated.

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

shelp (E)

shelp is meant to give a short help on the field 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

no_query

If set, it will not be possible to query on this field.

no_question

Used to only display the field name and the mark (display in tabular mode) button, and not the form INPUT field. No question allowed.

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

force_no_tab

The field will never appear in the tabular output.

forcefull_unitlabel

To force the output of the unitlabel when in 'full' mode.

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.

opt_constr

The opt_constr attribute (and its value) are used to allow the users to select some precoocked hardcoded sql constraints which can be added to the SQL where clause (logically ANDed).
The evaluated value of the opt_constr attribute is used to define which optional constraints are by default selected in the form, and which one are not by default selected. The users will anyway be able to select/deselect them all.
(Cfr OPT_CONSTR_URL form attribute above).

newtable

In full screen mode, the field which defines the newtable attrbute is going to be show as the first field of a new output table.

colspan

In full screen mode, the colspan value is passed to the HTML table field definition to control somehow the output table.

html_colspan

It sets a specific COLSPAN for the 'html' attribute. 'html_colspan' is only used when both the 'html' and the 'newtable' attributes are present. The 'newtable' forces a new table; the 'html' is displayed as the first record of the new table; the number of columns in the table are yet not known by the parser, hence the need for the html_colspan (since the number of columns depends on the number of 'sameline's encountered later).

index

No value attribute to inform WDB that the user input is meant to be of the kind 'afield like uservalue+"%"' and not of the usual type 'afield like "%"+uservalue+"%"'.

sql_constr

This must be a computed field attribute It is used to appen (logical AND) an SQL constraint (as from the eval $field{$f,'to_db'}) to the where clause.

userdefault

This is a field attribute which shall not be set by the developer in the FDF, but instead is set by WDB dynamically at run-time from the QUERY_STRING and only in /form mode.

no_select (E)

To control whether the field must or not appear in the select statement. If the evaluation of this attribute returns != 0, then the field is not queried. This feature might be useful in two cases:

• If the tables queried upon are dynamically chosen (e.g. you want (or not) to perform a join with table A depending on some conditions, e.g. if key_args present.) [See propabs.fdf in hst]
• If you use a group by on certain fields you might want to exclude the other fields from the select statement. (never tested this, but it should be possible).

range_proper

To control whether the parsing of the user provided input value for a possible range operator should be done with in the proper way '\s\.\.\s' as opposed to the de-facto standard way '\.\.' This attribute is especially relevant for those fields that might contain a sequence of dots in their values. In the example of a bibcode field, not declared 'range_proper', the user input value (which very likely contains a '\.\.' string) would be treated as a range of values, hence leading to a 'No data returned' page. [See propabs.fdf in hst]

target

to open the url in a different window
example: target = new window
will open the url in the window called newwindow (blanks removed!)

Virtual Observatory support

As of version 2.0 (03-JUN-2006) VOTable output format is available. Version 2.0 is backward compatible. No changes needed for existing FDFs. Though, existing FDFs need modifications to support VOTable format. An FDF to support the VOTable format MUST:

• declare it using the FORM attribute MDAWARE = 1 (existing FDFs have no MDAWARE attribute, hence they are as if MDAWARE=0)
• provide the mandatory VOTable attributes (datatype)
• provide optionally other VOTable attributes (arraysize, ucd, unit, coosys, ref)

The VOTable attributes can be provided in 2 ways:

• populating the MD database (the md_object, md_metadata tables, etc. [db=vo])
• placing the votable attributes in the FDF itself, as field attributes:
  • vodatatype, voarraysize, voref, voucd, vounit

The FDF-provided attributes have precedence over the MD database, that is, it is possible to use the MD database, but override only some of the attributes (e.g. typically the units, given that the from_db could be used to transform the output not preserving the original units). Other available new attributes are:

• VO_RESOURCE_HEADER and VO_TABLE_HEADER are two FORM attributes which WDB perl-evaluates, which can be used to add an entire VOTABLE section within the RESOURCE and TABLE elements respectively. An example is to use

  
          VO_RESOURCE_HEADER = print "<PARAM ID=\"anID\" name=\"aname\" ucd=\"aucd\" utype=\"autype\" value=\"avalue\"/>\n";
          

  to add a PARAM just under the RESOURCE element. Note: the VO_TABLE_HEADER should not be used to add VOTable FIELDs (that is done automatically by WDB). They are evaluated, hence they should contain printouts of valid VOTABLE(xml) constructs.

• VO_DESCRIPTION is a FORM attribute which contains the text to be presented in the first VOTable DESCRIPTION tag. WDB wraps it in a CDATA construct.

• COOSYS is a FORM attribute to indicate a reference frame for the coordinate system (using the appropriate voref); [deprecated; VOTable 1.2 will define a new mechanism]

• voinfo is a FIELD attribute that can be used to add a tag to the votable;

• CDATA (spelled uppercase) is a FIELD attribute that can be used to instruct WDB to wrap the field value in a CDATA XML construct; this is useful for those database attributes known to contain characters not supported by XML like &, <, and >.

The attribute no_votable can be used when a given field is not welcome in the output VOTable (but still is shown in the HTML output).

no_vounit, no_vodescription, no_voucd, no_voarraysize (evaluated) field attributes are used to not provide such metadata elements in the output VOTable.

Note: All the above-described VO attributes have an effect only when used in VOTABLE mode. The CDATA attribute, for example, when in HTML output mode, will not be used to trigger the escape function; that must be done within the from_db attribute (notice the asymmetry),

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.

$wdb_skip_query

A variable that the FDF can use to communicate back to wdb that an uploaded target condition is not valid; if not null, WDB will safely ignore such uploaded target and continue with the next uploaded target if any.

%wdb_no_select

A hash to store all the fields which have the no_select attribute.

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'})