Form Definition File Syntax

TOC:

• Form Attributes
• Field Attributes
• Internal Variables
• Functions

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 are ignored. In the original WDBI all characters after a '#' were ignored as well. That royally screwed up URLs that had '#' symbols in them, so I took that out. It is important that there is 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.

INCLUDE field type
If you find yourself adding the same FDF form and field attributes over and over in several FDFs, now you can put them all in a single file and just include them in your other FDFs. Just specify a line of the form:

    INCLUDE = /filesystem/path/to/your/include/file

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!

Because so many new attributes have been added, they have been divided into categories to organize them better so you can find what you are looking for more easily.

• Required FDF Attributes
• Query Constraint FDF Attributes
• Query Results Formatting FDF Attributes
• General FDF Attributes
• Counter FDF Attributes
• Normal Query And Result Headers
• Delete Attributes
• Insert Attributes
• Update Attributes

Required FDF Attributes

DATABASE (R)
Name of the database to use.

NAME (R)
Name of this form. Typically the same as the filename without the .fdf extension. This field used to be optional but is now required for proper WDBI behavior 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.) Any table name used in the JOIN, CONSTRAINTS, or ORDER attributes must be specified here as well.

TITLE (R)
Text for the <TITLE> tag in all WDBI pages. If a special header exists, such as D_HEADER or Q_HEADER, they are no longer used instead of the TITLE attribute.

Query Constraint FDF Attributes

CONSTRAINTS
Extra query constraints added to the where clause in the SQL select statment. Any table name referenced in the CONSTRAINT attribute must also be added to the TABLE attribute.

DISTINCT
Setting this attribute makes every 'select' done by the current FDF to be a 'select distinct'.

EVAL_SQL (E)
Allows you to add anything you want onto the end of a WDBI query.

JOIN
If more than one table is specified, join conditions must be specified here, and all tables referenced here must be specified in the TABLE attribute as well. (Use the column names given in the field definitions.)

Note: this is important so pay attention! If you use the JOIN attribute, the column attribute for every field used in the FDF must be fully qualified with the name of the table.

For example, if you join across the tables people and employment, and you have the fields name and address in the people table, and the fields salary and department in the employment table, you must change the column attributes for each field in the FDF to be like so: people.name, people.address, employment.salary, and employment.department. If you do not do this, WDBI does not know which fields belong to which table, and queries will not work. You have been warned.

MATCH_OPTION
Puts an option on the query form to let the user select all matching records or just find out how many records match a query without displaying them all. Requires no specified value.

ORDER
Column(s) to order by. If more than one column is given, separate by commas. (Used directly in a SQL select order by ... clause) Table referenced in the ORDER attribute must also be added to the TABLE attribute.

PASSWD
Lets you override the global value of $PSWD for the current FDF.

SERVER
Lets you override the global value of $SERVER for the current FDF.

UPCASE_QUERY
Use this attribute to uppercase any parameters entered by the user before creating the database query. Naturally, this only works if you have uppercased the data in your database. :) Doing things this way is much faster than using the matches/like/rlike operator. On large databases, speed becomes a big issue. Requires no specified value.

USER
Lets you override the global value of $USER for the current FDF.

Query Results Formatting FDF Attributes

CELL_FORMAT
Requires the TABLE_RESULTS attribute to be set. Defines a global attribute to apply to every cell in the results table, like so:

    CELL_FORMAT = ALIGN="LEFT" BGCOLOR="FFFFFF"

Note: you can override the global CELL_FORMAT attribute for selected table cells by using the cell_format field attribute for the selected cell(s).

FORCE_FULL
Forces output generated by the current FDF to be in full-screen format and doesn't allow the user to have the option of tabular output. Used with the new PRE_RESULTS form attribute and the new field formatting attributes, you have much more control over the output produced by WDBI.

HEADER_FORMAT
Requires the TABLE_RESULTS attribute to be set. Defines a global attribute to apply to every header in the results table, like so:

    HEADER_FORMAT = ALIGN=LEFT COLSPAN=2

Note: you can override the global HEADER_FORMAT attribute for selected table headers by using the header_format field attribute for the selected header(s).

MAXROWCOUNT
Lets you override the global value of $MAXROWCOUNT for the current FDF.

NO_BOLD_LABEL
Turns off bold labels on the query results page. Some browsers (like Netscape on a Mac) use strange fonts for bold so the results are not aligned correctly. Requires no specified value.

PRE_RESULTS
Forces query results to be displayed using the <PRE> tag. This is intended to be used with the output formatting tags. The TABLE_RESULTS and PRE_RESULTS tags are mutually exclusive. Requires no specified value.

ROWCOUNT
Lets you override the global value of $ROWCOUNT for the current FDF.

ROW_PAGING
WDBI can now display a page of query results and puts a button at the bottom of the page to see the next page of results. WDBI simply performs the same query for each page of output and bypasses records that have already been displayed.

TABLE_RESULTS
Puts query results into an HTML table. This works for both tabular and full-screen output. The TABLE_RESULTS and PRE_RESULTS tags are mutually exclusive.

Note: The default value for BORDER is 0. You can set table options in the FDF like so:



TABLE_RESULTS = BORDER=5 CELLPADDING=10 CELLSPACING=5



and so on. Any option recognized by the TABLE tag can be included. If you specify no options, results are put into a table with formatting standard for the user's Web browser.

SHOW_QUERY
Displays the query parameters entered by the user on every results page generated by using the current FDF. This feature is good for debugging, and for letting the user know what he/she really entered instead of what they thought they were entering. Requires no specified value.

General FDF Attributes

ADD_MENU (E)

Lets the user execute their own Perl functions to display something on the top of the query page, under the header and menu. Some things don't work well in the add_menu function which is usually added to the PERL attribute.

BODY_FORMAT (E)

Allows you to set options for the <BODY> tag such as the background color, text color, etc. of the Web browser. Use it like so:

    BODY_FORMAT = "BGCOLOR=\"#AABBCC\" TEXT=\"#FFFF00\"" 

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 wdbi.conf file. ) This behavior can be turned off with the NO_TAIL attribute.

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.

EXTRA_COLUMN_SIZE

Specifies the size of the box to use when displaying 'extra_columns'.

FOOTER (E)

Used to print a footer at the bottom of each page. Overrides the internal html_tail function that prints by default. See the NO_TAIL attribute.

HEADER_FONT

Allows you to select the font used to display the header information.

HELP_BUTTON

Lets you specify another image to use for the Help button on query forms instead of the default.

HOME_BUTTON

Lets you specify another image to use for the Home button on query forms instead of the default.

NO_CHECKBOXES

Turns off the checkboxes on the query form so users can't decide which fields appear on the results page.

NO_MAX_RECORDS_BOX

Turns off the max number of rows returned from query box. You know, this one:


Return a maximum of records from this query.


The number of rows to return is set to ROWCOUNT, if specified in the FDF, or $ROWCOUNT which is specified in wdbi.conf. You might use this to make sure all records are returned by setting ROWCOUNT = 10000000 and you don't want the user to change that.

NO_TAIL

Turns off the WDBI tag information at the bottom of pages generated by WDBI. Some people might not want the tag displayed. Requires no specified value.

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.

QUERY_BUTTON

Lets you specify another image to use for the Query button on query forms instead of the default.

QUERY_FORM

You can now use one FDF to format the query form, and specify another to use as a template to format the query results. Set QUERY_FORM equal to the name of the FDF to use as the query FDF. QUERY_FORM must be set in both the query and results FDF.

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'}";

RESULTS_FORM

You can now use one FDF to format the query form, and specify another to use as a template to format the query results. Set RESULTS_FORM equal to the name of the FDF to use as the results FDF. RESULTS_FORM must be set in both the query and results FDF.

SCRIPT

Lets you put JavaScript code (or other languages, too) into the <HEAD> section of a form. To access the code, see the script field attribute or the BODY_FORMAT form attribute.

SUB_QUERY_FOOTER (E)

If an FDF is used to generate the results of a sub-query from inside another FDF, this attribute can be used to display a footer under the sub-query results. If not used, nothing is displayed. An FDF can be used as a standalone and as a sub-query without having to create two different FDFs.

SUB_QUERY_HEADER

If an FDF is used to generate the results of a sub-query from inside another FDF, this attribute can be used to display a header over the sub-query results. If not used, nothing is displayed. An FDF can be used as a standalone and as a sub-query without having to create two different FDFs.

WDBI_HEADER (E)

Allows you to create a header that will replace the normal headers generated by WDBI.

Counter FDF Attributes

RECORD_COUNT_FILE

You can create a file that contains the number of records in a database and the date the database was last updated, then set RECORD_COUNT_FILE to the full path of the file, and WDBI will open the file and display the information on the query page. The file should be in the format: number|datestring. No numerical or date conversions are performed by WDBI so you can use text numbers (i.e. three hundred) and any date format you like just so they are separated with a '|' symbol.

VISITOR_COUNT_FILE

Create a file to be used as a counter for a particular Web page generated by WDBI and set VISITOR_COUNT_FILE equal to the full path to that file. WDBI will use the file to count Web visitors to the Web page.

VISITOR_COUNT_TEXT

This text will be prepended to the number of visitors who have hit the current Web page. (i.e. Visitors in the last 20 minutes: 2345)

VISITOR_LOCK_FILE

The name of the file to use when accessing the counter file for the current FDF. This keeps more than one person from trying to update the counter file at one time. All visitors to the same Web page must use the same lock file because they are all using the same counter file. The lock file is created in the /tmp directory. If you want to change this, edit the count_visitor subroutine in the WDBI program.

Normal Query And Result Headers

Q_HEADER

Text for the first <H1> tag in the query form.

R_HEADER

Text for the first <H1> tag in the result page.

DEF_HEADER

Text for the first <H1> tag in the result of a default query page.

Note: in the original WDBI, this was D_HEADER. The name was changed because anything starting with D_ is now used to identify attributes associated with the delete action.

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.

DEF_HTML

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

Delete Attributes

ALLOW_DELETE

Allows users access to the delete function using the current FDF.

Ordinarily, WDBI performs a check to be sure the data in the database has not changed since a user selected the data for delete. If the data has changed, the update is aborted to keep from overwriting another user's changes. If you prefer that WDBI not make this check, specify:

    ALLOW_DELETE = nocheck

D_HEADER

Text for the first <H1> tag in the delete form. Note: D_HEADER used to be the default header. To make nomenclature more regular, the default header is now DEF_HEADER.

DELETE_RESPONSE (E)

The message to display to the user upon successful deletion of data.

DR_HEADER

Text for the first <H1> tag in the delete results page.

D_HTML

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

DR_HTML

Extra HTML text to add to the delete results page just below the header.

POST_DELETE_CHECK

Tells WDBI to execute the subroutine post_delete_check that must be defined in the PERL attribute. You write the code inside the subroutine to do whatever processing you want. This subroutine is executed after the selected data has been deleted from the database.

The result of the subroutine must be returned in an array. The first element in the array is required and is the return code. 0 indicates the subroutine executed correctly, anything else indicates an error and will cause WDBI to stop processing. The second element in the array is optional and is a message to display to the user on success or failure. If the second element does not exist, nothing is displayed.

PRE_DELETE_CHECK

Tells WDBI to execute the subroutine pre_delete_check that must be defined in the PERL attribute. You write the code inside the subroutine to do whatever processing you want. This subroutine is executed before the selected data has been deleted from the database.

The result of the subroutine must be returned in an array. The first element in the array is required and is the return code. 0 indicates the subroutine executed correctly, anything else indicates an error and will cause WDBI to stop processing. The second element in the array is optional and is a message to display to the user on success or failure. If the second element does not exist, nothing is displayed.

Insert Attributes

ALLOW_INSERT

Allows users access to the insert function using the current FDF.

I_HEADER

Text for the first <H1> tag in the insert form.

INSERT_RESPONSE (E)

The message to display to the user upon successful insertion of data.

IR_HEADER

Text for the first <H1> tag in the insert results page.

I_HTML

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

IR_HTML
Extra HTML text to add to the insert results page just below the header.

POST_INSERT_CHECK
Tells WDBI to execute the subroutine post_insert_check that must be defined in the PERL attribute. You write the code inside the subroutine to do whatever processing you want. This subroutine is executed after the entered data has been inserted sucessfully into the database.

The result of the subroutine must be returned in an array. The first element in the array is required and is the return code. 0 indicates the subroutine executed correctly, anything else indicates an error and will cause WDBI to stop processing. The second element in the array is optional and is a message to display to the user on success or failure. If the second element does not exist, nothing is displayed.

As an example of how to use this feature, you can write code to perform a calculation based on user input and change the value of a field accordingly.

PRE_INSERT_CHECK
Tells WDBI to execute the subroutine pre_insert_check that must be defined in the PERL attribute. You write the code inside the subroutine to do whatever processing you want. This subroutine is executed after all value processing has been completed (i.e. all to_db and similar functions have been performed) but before the entered data has been inserted into the database.

The result of the subroutine must be returned in an array. The first element in the array is required and is the return code. 0 indicates the subroutine executed correctly, anything else indicates an error and will cause WDBI to stop processing. The second element in the array is optional and is a message to display to the user on success or failure. If the second element does not exist, nothing is displayed.

As an example of how to use this feature, you can write code to grab a key value that was just generated by the database and display it to the person who inserted the data.

Update Attributes

ALLOW_UPDATE

Allows users access to the update function using the current FDF.

Ordinarily, WDBI performs a check to be sure the data in the database has not changed since a user selected the data for update. If the data has changed, the update is aborted to keep from overwriting another user's changes. If you prefer that WDBI not make this check, specify:

    ALLOW_UPDATE = nocheck

POST_UPDATE_CHECK

Tells WDBI to execute the subroutine post_update_check that must be defined in the PERL attribute. You write the code inside the subroutine to do whatever processing you want. This subroutine is executed after the entered data has been updated sucessfully in the database.

The result of the subroutine must be returned in an array. The first element in the array is required and is the return code. 0 indicates the subroutine executed correctly, anything else indicates an error and will cause WDBI to stop processing. The second element in the array is optional and is a message to display to the user on success or failure. If the second element does not exist, nothing is displayed.

PRE_UPDATE_CHECK

Tells WDBI to execute the subroutine pre_update_check that must be defined in the PERL attribute. You write the code inside the subroutine to do whatever processing you want. This subroutine is executed before the entered data has been updated in the database.

The result of the subroutine must be returned in an array. The first element in the array is required and is the return code. 0 indicates the subroutine executed correctly, anything else indicates an error and will cause WDBI to stop processing. The second element in the array is optional and is a message to display to the user on success or failure. If the second element does not exist, nothing is displayed.

U_HEADER

Text for the first <H1> tag in the update form.

UPDATE_RESPONSE (E)

The message to display to the user upon the successful update of data.

UR_HEADER

Text for the first <H1> tag in the update results page.

U_HTML

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

UR_HTML

Extra HTML text to add to the update results form just below the header.

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 !

Because so many new attributes have been added, they have been divided into categories to organize them better so you can find what you are looking for more easily.

• Required Field Attributes
• Key Field Attributes
• Query (Select, Insert, Update, or Delete) Form Field Attributes
• Tabular Output Field Attributes
• Full-Screen Output Field Attributes
• Output Field Attributes Used in Both Tabular and Full-Screen Output
• Item Selection Field Attributes
• Special Field Attributes

Required Field Attributes

FIELD (R)

Field identifier. Used internally to uniquely identify a field. The FIELD attribute must be the first attribute specified for a field. Other fields can go in any order. The FIELD attribute must be unique for each field in an FDF! If you have two fields with the same name, the label may be the same, but you must change the FIELD values for the dublicate field(s).

column (R)

Database column definition. Defaults to the value of FIELD. Depending on your database, column values can include computed fields, 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. Note: the column attribute is not required on the MORE, Insert, Update, or Delete fields.

label (R)

Label/title in forms etc.

length (R)

Length of field including formatting etc.

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.

Key Field Attributes

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

Note: the primary_key and key attributes are not the same. The key attribute is ignored on insert, update, and delete actions. The primary_key attribute is ignored during queries. This preserves the original function of 'key' while introducing new functionality for a primary key attribute.

primary_key

Specifies a database field as a primary field for particular table. Only one primary key field may be specified per FDF. Any foreign_key attributes will reference the primary_key field for their value when using join conditions.

Note: the primary_key and key attributes are not the same. The key attribute is ignored on insert, update, and delete actions. The primary_key attribute is ignored during queries. This preserves the original function of 'key' while introducing new functionality for a primary key attribute.

foreign_key

This attribute identifies a field as a key in one table that refers to the primary key of another table. This attribute is used to insert, update, and delete across table joins. The value of the primary key is used to deal with the data in foreign key tables. In order to use the primary key value, the primary_key attribute must be used as well.

serial_field

Not neccesarily a key field, but enhances the primary_key attribute. Designates a database field that is incremented on insert. It's up to you or your database to actually provide the incremented value. :)

Some databases, such as mSQL 2, use sequences that provide you with a value before an insert. You must select a new sequence value, then use that value on an insert. Other databases, such as Informix, require you to insert a 0 in the serial field, and the database will insert a new value. The new value is returned by the database.

If you designate a field in the FDF to be both primary_key and serial_field, WDBI will use the newly generated key value as the value of any foreign_key fields when inserting into multiple tables across join conditions. In this manner, WDBI supports the use of unique key values generated by a database, even across join conditions on an insert.

This differing methodology requires WDBI to support two completely different methods of serial value generation. You will need to find out which method your database uses and tell WDBI which method to use.

For a database that generates a serial value prior to insert, such as mSQL 2, specify the serial_field attribute like so:


     serial_field = pre_insert


Note: be sure you have created a sequence on the table containing the serial field, or no unique value will be generated.

For a database that generates a serial value on insert and returns the value, specify the serial_field attribute like so:


    serial_field = post_insert

Note: be sure you have specified the field as serial type in the database, or no unique value will be generated.

Query (Select, Insert, Update, or Delete) Form Field Attributes

compute_date

Generates a system date when inserting a record into the database. The format of the date is defined in the dbi_dateformat subroutine in the _dbi.pl file that matches your database. When a record is updated, a new date is computed and the record gets that date. If you don't like the format of date generated by WDBI, you can use the to_db attribute to change it to whatever you like.

If you want the user to be able to edit the date provided by WDBI, set:


    compute_date = edit

and the date will be displayed in a textbox.

compute_datetime

Generates a system date and time when inserting a record into the database. The format of the date is defined in the dbi_dateformat and dbi_timeformat subroutines in the _dbi.pl file that matches your database. When a record is updated, a new datetime is computed and the record gets that date. If you don't like the format of datetime generated by WDBI, you can use the to_db attribute to change it to whatever you like.

If you want the user to be able to edit the date provided by WDBI, set:


    compute_datetime = edit

and the datetime will be displayed in a textbox.

default (E)

Default value to insert in the query form's input field before presenting it to the user. The user is free to change or remove this value.

form_buttons

Puts a menu of buttons on select, insert, update, or delete forms after the field that contains the form_buttons attribute. This is useful for long forms where the user can get frustrated scrolling to the the top or bottom of the form to push a button.

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.

html (E)

The value of this attribute is inserted as HTML text on the line before the current field on the query, insert, update, and delete forms only. Use pre_html or post_html to add HTML text to results pages.

label_linebreak

This puts a query form label on the line above the textbox.

max_length

This attribute sets the absolute maximum size of the field boxes created by WDBI. This helps prevent users from entering data longer than the database field will accept.

no_delete

If set, a field will not show up on the delete form.

no_edit

If set, this attribute displays a field value so a user cannot edit it.

no_insert

Prevents a field from accepting inserted data. This is used for serial or date fields where the value is automatically inserted.

non_null

Requires a field to be filled in by the user before an insert will be performed. On the insert form, required fields are marked with a !.

no_old

On updates and deletes, WDBI puts the previous values of fields into the Web page as hidden elements. If the old values happen to contain HTML or other unusual values, strange things can appear on your query forms. Use the no_old attribute to prevent this. Any field marked with the no_old attribute, must also be marked with the no_where attribute. Trust me, it must.

no_query

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

no_update

Prevents a field from accepting updated data. This prevents the value of a field, such as a key field, from changing on an update.

no_where

When WDBI constructs an update or delete statment, the old field values are used to construct the where clause so make sure you are updating or deleting the correct record. Some fields, such as BLOBS, would make this a silly thing to do. To exclude a field, for whatever reason, add the no_where attribute to the field definition.

sameline

If set the field will appear on the same line as the previous on the query forms only.

script

Lets you put JavaScript code (or other languages, too) into the HTML tag of a field when a query form is generated. Also see the SCRIPT form attribute.

textarea

If you need a larger text entry box than the standard HTML INPUT tag, you can use the textarea attribute to specify an HTML TEXTAREA tag where you can include any parameter the tag accepts, like so:

    textarea = COLS=90 ROWS=8

Note: The TEXTAREA tag is assigned a NAME by WDBI that is the name of the database field it is related to. DO NOT specify a NAME in the textarea attribute, or undesirable behavior may occur.

to_db (E)

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

unitlabel

Unit label to add at the end of the query fields / result values.

Tabular Output Field Attributes

cell_format

Requires the TABLE_RESULTS FDF attribute to be set. This attribute allows you to set characteristics for the current cell of the output table. Use this to align text, set the background color of cells, etc. like so:

    cell_format = ALIGN="LEFT" BGCOLOR="FFFFFF"

and so on.

Note: If you want to define a cell format for an entire FDF, you can use the CELL_FORMAT form attribute. If you want some fields to have special formatting, you can use the cell_format to override the global CELL_FORMAT attribute.

drill_down

When query results are displayed, values in a field with this attribute will be displayed as a hyperlink. Clicking the hyperlink will display all results in the database with values in this field which match the current value. (This is done by adding ~ to the URL. WDBI can't use '=' because that has special meaning to the Web browser.)

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

header_format

Requires the TABLE_RESULTS FDF attribute to be set. This attribute allows you to set characteristics for the headers of an output table. Use this to align text, span more than one column, etc. like so:

    header_format = ALIGN=LEFT COLSPAN=2

Note: If you want to define a header format for an entire FDF, you can use the HEADER_FORMAT form attribute. If you want some headers to have special formatting, you can use header_format to override the global HEADER_FORMAT attribute.

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

tablen

The field can appear in the tabular output, but will be truncated to the length specified as the value of this attribute.

Full-Screen Output Field Attributes

line_break

Forces an extra newline after the current field. Requires the PRE_RESULTS FDF attribute to be set.

no_dots

Do not print padding dots between the label and field data on full-screen output for the current field.

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.

no_label

Prevents the printing of a field label on full-screen output. This is used if you want to use the pre_html attribute to print a custom label.

no_space

Used with FORCE_FULL, if you have fields on the same line and there are unwanted spaces between the field values, this attribute removes them.

outlen

Sets the length of a field when it is displayed in full-screen mode.

post_html (E)

The value of this attribute is inserted as HTML on the line after the current field only on full-screen output.

post_space

Puts the indicated number of spaces after the current field. Requires the PRE_RESULTS FDF attribute to be set.

pre_html (E)

Puts HTML text before a field on full-screen output only.

Note: in the original WDBI, this attribute was called simply html. The name was changed to more accurately reflect what it does and to show how it complements the new post_html attribute.

pre_space

Puts the indicated number of spaces before the current field. Requires the PRE_RESULTS FDF attribute to be set.

sameline_out

If set the field will apear on the same line as the previous on full-screen output only. Requires the PRE_RESULTS FDF attribute to be set.

separator

Lets you put a character separator between two fields on full-screen output. If you specify no_label and sameline_out for two adjacent fields in the FDF, they will be displayed with the selected character between them. For example, if the separator is a '-', you can do something like this:

    Range...: 10 - 20 Hz

sort_by

When query results are displayed, this attribute causes the label over a field to be a hyperlink. Clicking on the hyperlink redisplays the results sorted by the selected field. (This is done by adding 'wdb_order=' to the URL.)

Output Field Attributes Used in Both Tabular and Full-Screen Output

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.

encode

Some complex strings need to be hex encoded before being displayed by a Web browser. If your string might contain characters a browser could misinterpret, add this attribute to the field and WDBI will call the &cgi_encode() function to encode the string.

from_db (E)

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

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

lookup

Displays a value selected from the database in place of the value actually retrieved from a query. Compliments the makelist attribute. The syntax is as follows:

    lookup=tablename%fieldname%target_fieldname%target_value%extra

where tablename is the name of the table to search, fieldname is the name of the field to select, target_fieldnameis the field to match against, target_value is the value to match, and extra is any extra query constraints added on to the select. The first four fields are required and the fifth is optional. From the above syntax, the following query would be constructed:

   select fieldname from tablename where target_fieldname=target_value and extra

Note: The target_value must be a numerical value. There is no way for WDBI to determine the datatype, so as most keys are numerical a number is assumed.
Another note: If you use Sybase, this attribute only works with DBD::Sybase version 0.12 and better.

unitlabel

Unit label to add at the end of the query fields / result values.

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=$WDBI/$form{'NAME'}/query/$val{'keyfield1'}::$val{'keyfield2'}

Please note the use of the $WDBI variable instead of the name of the script (http://.../cgi-bin/wdbi/). This makes it easier to use more than one version of the wdbi script ( for example a development version and an installed version ).

Item Selection Field Attributes

enum

Enumerated 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

enum_perl (E)

Used with the enum attribute. Allows you to add Perl code that returns a correctly formatted string to use as the source of the 'enum' attribute. For example:

    enum
    enum_perl = &my_enum_sub

multiple

Used with the enum attribute. 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. If you want to set the size of the scroll box created in your Web browser, do like so:

multiple = 4

or whatever you want the size to be.

size

Used with the enum attribute. Changes a pulldown list to a scrollbox and sets the size of the box.

makelist

Similar to the enum attribute, but where enum specifies a fixed list of values, the makelist attribute selects a distinct list of items from the database to create dynamic lists. The syntax is as follows:

    makelist = tablename%fieldname[%searchkey]

where tablename is the name of the table to search, fieldname is the name of the field to select, and searchkey is the optional key value to search for. For example,

    makelist = employees%name

would return the name of all employees. If you want to search for employees by group id and only return those who match a given group you can do something like this:

    makelist = employees%group_id,name%group_id=4

which would return a list of the names of all employees in group number 4. Any constraints added after the final '%' are made into a 'where' clause, i.e. the above example would add 'where group_id=4' to the query.

list_display (E)

Allows you to access the inner workings of WDBI to format the output of a makelist query. Values returned from a makelist query are stored in the Perl hash '%myrow'. The list_display attribute lets you access this hash to customize your list items. For example, if you use:

    makelist = employees%employee_id,name,department

then use:

    list_display = $myrow{name} ($myrow{department})

the displayed items will show the employee name and department in the list. You can access any field you specify in the makelist attribute from within the list_display attribute. Note: The default behavior for display is to use the first field as the value of the list item and the second is displayed to the user. If no second field is specified, the first field is used in the display.

list_first_element

Let's you define the text for the first element of a picklist or scrollbox. The default is a blank field. (The first field is mandatory so that if no item is selected from the list, WDBI knows not to include a query parameter for that field in the query.)

list_format

Used with the makelist attribute. This attribute determines if a list will be a set of radio buttons, or a pulldown or scrolling list. Legal values are 'checkbox', 'picklist', or 'radio'. (The list_size attribute creates a scrolling list from a 'picklist'. Just FYI.)

list_indent

Used with the makelist attribute. Indents any type of list by putting <UL> </UL> tags around the list. This can make lists easier to see and read.

list_linebreak

Used with the makelist attribute. This attribute puts a newline between the list label and the list box or buttons.

list_match

Used with the makelist attribute. Lets you set the operator for each element in the list. For example, if you want to search for exact matches, you would set list_match = == and the operator '==' will be prepended to each element of the list. You can use any operator your database understands. (The default is not to use an operator which performs a substring match, and is very expensive in database terms.)

list_multi

Used with the makelist attribute. Allows users to select multiple items from a scrolling list. Multiple values are or'ed together in the query.

list_off

Turns off the makelist attribute for selected WDBI functions. For instance, to only generate a drop down list on the insert form, do:

list_off = query,update

Legal values are query, insert, or update. (Lists are not generated for delete forms.)

list_oneline

Used with the makelist attribute. When creating a list of radio buttons on the WDBI query form, this attribute puts all radio buttons on the same line. The default is to put each button on a line by itself. You can specify the number of items to put on each line like so:

list_oneline = 3

or whatever number you want to use.

list_order

Allows you to specify which field to order a makelist query by. The field must be specified in the makelist attribute or a SQL error will result.

list_size

Used with the makelist attribute. Changes a pulldown list to a scrollbox and sets the size of the box.

list_value (E)

Allows you to access the inner workings of WDBI to format the output of a makelist query. Values returned from a makelist query are stored in the Perl hash '%myrow'. The list_value attribute lets you access this hash to customize your list items. For example, if you use:

    makelist = employees%employee_id,name,department

then use:

    list_value = $myrow{name}

the employee name will be used as the value of the list item. You can access any field you specify in the makelist attribute from within the list_value attribute. Note: The default behavior for display is to use the first field as the value of the list item and the second is displayed to the user. If no second field is specified, the first field is used in the display.

list_where (E)

Allows you to specify a 'where' clause for the makelist attribute that gets run through Perl's eval. This lets you write your own Perl code, use Perl variables, or grab the value of %ENV. Don't forget to quote the value!

operators

Works like the enum operator, but puts a list of operators (equals, matches, <, >, =, <=, etc) in a pulldown list next to the query field. This way the WDBI developer can add operators appropriate to a field, and the user can more easily determine how to use operators. The original method of entering the operator in the query field along with the query parameter still works, and will override anything selected from the operator list. May be used in addition to the enum or makelist attributes.

Special Field Attributes

ignore_select

Ignores a field when creating the SQL select clause, but still uses it in the where clause if the user enters query parameters for the current field in the query form.

This enables you to perform conditional joins that only search for data in a second table if the user requests it. The data from the primary is returned even if there is no data in the second table related to the first. This is sort of like an inner join, but if your database doesn't support inner joins, you can do the same thing with WDBI.

You might also check into the sub_query attribute.

image_src (E)

Identifies an attribute as a image that will be provided from an external source. It would be nice if WDBI could select the image out of the database and feed it directly to a Web browser, but the only way a browser can recognize an image is if it's inside an <IMG> tag. So, whatever the image_src attribute is set to is put inside an IMG tag. This lets you point at an external image file, or use an external CGI program to pull one out of the database. For example, you can do this:

    image_src = "http://somewhere/cgi-bin/get_image.cgi/$val{'key'}"

to pull an image out of the database based on the value of a field in the current record. Please replace key with the name of your key field.

Note: You can include more than just the SRC tag in the image_src attribute, such as HEIGHT=100 WIDTH=100.

password

If you have a field used for entering passwords and you don't want people catching them by looking over your shoulder, this attribute causes a textbox to act like a standard password box and display an asterisk (*) for each letter typed.

serial_field

Designates a database field that is incremented on insert. It's up to you or your database to actually provide the incremented value. :)

See the Key Field Attributes section for information on using the serial_field attribute with the primary_key attribute.

For a database that generates a serial value prior to insert, such as mSQL 2, specify the serial_field attribute like so:


     serial_field = pre_insert


Note: be sure you have created a sequence on the table containing the serial field, or no unique value will be generated.

For a database that generates a serial value on insert and returns the value, specify the serial_field attribute like so:


    serial_field = post_insert

Note: be sure you have specified the field as serial type in the database, or no unique value will be generated. Another note: If you use SQL Server, this attribute is only supported under the InterLink ODBC driver. I've also tested the Microsoft and Intersolv drivers, and neither will support this feature.

sql_check (E)

Lets you specify SQL statement(s) to execute and if the results come back > 0, execute a statement specified in sql_do. You can specify multiple SQL statements in sql_check and actions in sql_do. They are processed in pairs so if the sql_check item fails, the sql_do is discarded. All sql_check items are processed in order and all that succeed are processed.

sql_do (E)

The action to perform if a matching sql_check succeeds.

sub_query (E)

Lets you execute a SQL query at any point in an FDF and display the results using another FDF. If no results are returned from the SQL query, nothing is displayed. The syntax is like so:

    sub_query = employee|"group_id = \"$val{'group_id'}\""

This will use the employee.fdf file to display all employees with the current group_id. This lets you display multiple external records that are related to the current record. Use the SUB_QUERY_HEADER form attribute to specify an overall header to the sub_query results.

Internal Variables

There are some internal Perl variables that can be referenced in the attribute definitions above. Most of them have 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.

$WDBI

The name of the script used to access this form. This is set by wdbi on each invocation. If used in url references it is a lot easier to test different versions of wdbi 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.

Note: May be overridden in the FDF with the MAXROWCOUNT attribute.

$ROWCOUNT

The default value for the above field. This controls the maximum number of rows that can be returned from a query.

Note: May be overridden in the FDF with the ROWCOUNT attribute.

Functions

These are functions build into WDBI - 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 wdbi.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 = "$WDBI/$form{'DATABASE'}/$form{'NAME'}/query/$val{'keyfield'}"

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

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