Form Definition File Syntax

TOC:

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]

where the name of the attribute is required, but the specified value may be optional. See the definitions below to determine if an attribute requires a 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.

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
and anything you put in the included file will show up in WDBI as if they were explicitly written in the FDF.

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!

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.

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

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

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

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

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

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

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.

DATABASE (R)
Name of the database to use.

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.

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

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.

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

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

DELETE_RESPONSE (E)
The message to display to the user upon successful deletion of data.

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

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.

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

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

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

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

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

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_FONT
Allows you to select the font used to display the header information.

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

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.

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

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

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.

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

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.

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

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.

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.

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.

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)

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

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.

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.

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.

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

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.

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.

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.

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

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

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.

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

R_HTML
Extra HTML text to add to the result page 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'}";

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.

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.

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.

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.

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

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.

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.

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 or CONSTRAINT attributes must be specified here.

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:

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.

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.

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

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

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.

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.

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

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

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.

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

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

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"
yadda, yadda, blah, blah.

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.

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

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.

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.

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.

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

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.

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

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

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 field attribute, the primary_key attribute must be used as well.

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.

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

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.

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.

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

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.

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 = "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.

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

label
Label/title in forms etc. Defaults to the value of FIELD

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

length (R)
Length of field including formatting etc.

line_break
Forces an extra newline after the current field when results are displayed using the PRE_RESULTS tag.

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

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!

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.

makelist
Creates a distinct list of items selected from the database. The syntax is as follows:
    makelist = tablename%fieldname[%search parameters]
where tablename is the name of the table to search, fieldname is the name of the field to select, and search parameters is the optional 'where' list to constrain the search. 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.

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.

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_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_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_query
If set, it will not be possible to query on this field.

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

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

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

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

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

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

operators
Works like the enum operator. 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.

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

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.

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 when results are displayed using the PRE_RESULTS tag.

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 when results are displayed using the PRE_RESULTS tag.

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.

sameline
If set the field will apear on the same line as the previous.

sameline_out
If set the field will apear on the same line as the previous on full-screen output 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.

separator
Lets you put a character separator between two fields. 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

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

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

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

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.

tablen
The field can appear in the tabular output, but will be truncated to the length specified as the value of this 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.

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.

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

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

Copyright © 1996-98 Bo Frese Rasmussen and Jeff Rowe