Next: How to use WDB
Up: WDB Installation and Users
Previous: Writing Form Definition Files
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
Blank lines are ignored. In the original WDB 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.
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.
- 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
WDB 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 WDB pages. If a
special header exists, such as D_HEADER or Q_HEADER,
they are no longer used instead of the TITLE attribute.
- 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.
- 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, WDB 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.
PASSWORD
-
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.
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).
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
-
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 wdb.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.
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:
The number of rows to return is set to ROWCOUNT, if specified in the FDF, or
$ROWCOUNT which is specified in wdb.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 WDB tag information at the
bottom of pages generated by WDB. 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.
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.
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 WDB 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 WDB 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 WDB and set VISITOR_COUNT_FILE equal to the full path to that file. WDB
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 WDB program.
- 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 WDB, 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.
- ALLOW_DELETE
-
Allows users access to the delete function using the current FDF.
Ordinarily, WDB 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 WDB 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.
- DR_HEADER
-
Text for the first
<H1>
tag in the delete results page.
- DQ_HEADER
-
Text for the first
<H1>
tag in the delete query form.
You must first perform a query to find the record you want to delete.
- 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.
- DQ_HTML
-
Extra HTML text to add to the delete query form just below the header.
- 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.
- 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.
- ALLOW_UPDATE
-
Allows users access to the update function using the current FDF.
Ordinarily, WDB 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 WDB not make this check, specify:
ALLOW_UPDATE = nocheck
- U_HEADER
-
Text for the first
<H1>
tag in the update form.
- UR_HEADER
-
Text for the first
<H1>
tag in the update results page.
- UQ_HEADER
-
Text for the first
<H1>
tag in the update query form.
You must first perform a query to find the record you want to update.
- 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.
- UQ_HTML
-
Extra HTML text to add to the update query form just below the header.
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.
- 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
-
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, WDB 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, WDB supports the use of unique key values
generated by a database, even across join conditions on an insert.
This differing methodology requires WDB to support two completely different
methods of serial value generation. You will need to find out which method
your database uses and tell WDB 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.
compute_date
-
Generates a system date of the form MM/DD/YY when inserting a
record into the 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 WDB, or your database doesn't understand it, you can use the
to_db attribute to change it to whatever you like.
- 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
-
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.
max_length
-
This attribute sets the absolute maximum size of the field boxes created
by WDB. This helps prevent users from entering data longer than the database
field will accept.
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_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 WDB 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.
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 WDB
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.
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.
- 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.
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.
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 WDB, 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
- 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 WDB 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.)
- 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=$WDB/$form{'NAME'}/query/$val{'keyfield1'}::$val{'keyfield2'}
Please note the use of the $WDB variable instead of the
name of the script (http://.../cgi-bin/wdb/). This makes it
easier to use more than one version of the wdb script ( for
example a development version and an installed version ).
- 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.
- 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, but display the
employee name instead of the group_id, you can do something like this:
makelist = employees%group_id,name%4
which would return a list of the names of all employees in group number 4.
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, WDB 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_oneline
-
Used with the makelist attribute. When creating a list of radio
buttons on the WDB query form, this attribute puts all radio buttons on
the same line. The default is to put each button on a line by itself.
list_size
-
Used with the makelist attribute. Changes a pulldown list to a
scrollbox and sets the size of the box.
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 WDB 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.
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 WDB.
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 WDB 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.
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.
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.
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.
- $WDB
-
The name of the script used to access this form. This is set by
wdb on each invocation. If used in url references it is a lot
easier to test different versions of wdb on the same FDF
files. This variable should not be changed !
- $MAIN_MENU
-
A URL to the main menu of forms, or the homepage. This URL is
used for the 'Home' button.
- $QUERY_HELP
-
A URL to the query help. This URL is used for the 'Help' button.
- $NULL_VALUE
-
The value to display as the NULL value. (default is an empty
string "").
- $MAXROWCOUNT
-
The Maximum allowed value for the 'Return max .... rows' field.
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.
These are functions build into WDB - However you can always add your own
functions as well and include them either directly in the FDF file (under the
PERL form attribute) or include them in your own Perl package and
install it in your Perl library directory - then include them with the
Perl 'require' statement in the PERL attribute or in the wdb.conf file
to make them available in all your FDF files.
- &add_menu( $text, $href, $img )
-
This function can be used in the PERL form attribute to add
extra menu options next to the Submit, Reset, Help, etc.
buttons. Either a text or a GIF button can be used. ( See appendix
on how to create GIF buttons. )
- $text
-
- is the text label to use, either directly or as the
ALT attribute if a GIF button is supplied.
- $href
-
- is the URL to execute when the button is pressed.
- $img
-
- is the URL to the GIF file to use as button. If this
argument is left out a normal text link is created
instead.
- &cgi_encode( $str )
-
Encodes a string so it doesn't cause problems in a URL. If you have
a keyvalue that could contain special characters like spaces, %
signs etc. you can't just included it in a normal url like :
url = "$WDB/$form{'DATABASE'}/$form{'NAME'}/query/$val{'keyfield'}"
In this case you would have to encode the key value
using cgi_encode like this :
url = "$WDB/$form{'DATABASE'}/$form{'NAME'}/query/" . &cgi_encode($val{'keyfield'})
Next: How to use WDB
Up: WDB Installation and Users
Previous: Writing Form Definition Files
Copyright © 1996 Bo Frese Rasmussen and Jeff Rowe