How to provide information through WDB

Once you have installed WDB you have to define which parts of your database you want to make available, and how it should look. This is done by creating a set of Form Definition Files (FDFs).

An FDF is like a view on the database specifying which table(s) and fields should be accessible through each WDB Query Form.

Creating an FDF

As your first FDF try to make a simple one - only involving one table, with a unique index on one field. Let's say the table is called sample and are located in a database called mydb. The table looks like this :

create table sample 
        (userid         char(10)        not null,
         name           varchar(50)     not null,
         office         smallint        null,
         phone          char(4)         null)

(The unique key is the 'userid' column )

Now create a subdirectory in your FDF directory (The one you specified in "$formdir" when configuring the WDB script ) and call it mydb ( You are free to call it something else though - this is just a way of grouping related FDF's ).

mkdir  mydb

Now change to this new directory and run mkfdf :

cd mydb
mkfdf -d mydb -t sample -k userid

That's it ! Now you have a file called sample.fdf, which can be used via the url http://your.server/cgi-bin/wdb/mydb/sample/form.

Please note how the URL is composed : 'http://your.server/cgi-bin/wdb' is the normal path to the wdb script you just installed. 'mydb' is the name of the directory you created above. 'sample' is the name of the FDF without the '.fdf' extension. The keyword 'form' tells WDB to create a query form for the specified FDF file (See also 'How to use WDB').

The sample.fdf file will look like this :

NAME         = sample 
TABLE        = sample 
DATABASE     = mydb 
TITLE        = sample 
Q_HEADER     = sample Query Form 
R_HEADER     = sample Query Result 
#DOCURL      = # URL to documentation.

#JOIN        = # Join condition goes here ..
#CONSTRAINTS = # Extra query constraints goes here ....
#ORDER       = # ORDER BY columns goes here ...

#RECTOP      = #Record title goes here ....
#PERL        = # Extra perl commands goes here ....
#------------------------------------

FIELD  = userid 
label  = Userid
column = userid 
type   = char			# char 
length = 10
key
url    = "$WDB/devdb/$form{'NAME'}/query/$val{'userid'}"

FIELD  = name 
label  = Name
column = name 
type   = char			# varchar 
length = 50

FIELD  = office 
label  = Office
column = office 
type   = int			# smallint 
length = 2

FIELD  = phone 
label  = Phone
column = phone 
type   = char			# char 
length = 4

Customizing the FDF

Now you might want to change it a little bit : Changing the title (TITLE) and the headers (Q_HEADER, R_HEADER, D_HEADER ) perhaps adding some introductory messages (Q_HTML, R_HTML, D_HTML) explaining what kind of information you can search trough using this form, or perhaps change the appearance of some of the fields.

The real power of WDB lies in the fact that some of the fields are evaluated as Perl expressions.

Let's first make a simple example : In the above example the table only stored the local extension number in the 'phone' field. Now say that you would like to prepend this with the number of the your company then a '+' sign and then the local number from the database, so outside users could use the telephone numbers as well. All you have to do is to add the following line in the definition of the phone field (and change the length attribute to the new length) :

from_db = "(089) 320 06 + " . $val{'phone'}
length = 19

Now lets say that the name field in the above example can contain special characters in LaTeX format. To display these properly we will have to convert them to the equivalent HTML codes before presenting them to the user. To do this we first write a small perl function : textohtml ( full text is available from the contrib directory in the WDB distribution. )

sub textohtml
{
    local ( $str ) = @_;

    $str =~ s/\\"{u}/&uuml;/g;
    $str =~ s/\\"{U}/&Uuml;/g;
    ....
    return ( $str );
}

This function takes as an argument the LaTeX encoded string from the database and outputs the equivalent HTML encoded string. - Now to use it in the above example simply add the following from_db attribute to the 'name' field :

from_db = &textohtml( $val{'name'} );

If you are used to Perl - this will look familiar. In general any perl expression can be used in the from_db attribute (and any other attribute that are evaluated ). Please refer to the FDF Syntax page for a full list of available attributes and their use, and your Perl man page for an explanation of how to write perl expressions.

Perl Reference Materials

To get the full benefit of WDB you need to know a bit about Perl. I can recommend the book : Programming Perl by Larry Wall and Randal L. Schwartz from O'Reilly. The first few chapters should get you started.
There are also some good Perl reference materials available on-line on the Web.