3 Writing Form Definition Files

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 : (The unique key is the 'userid' column )

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

Now create a subdirectory in your FDF directory (The one you specified in $formdir when configuring WDB ) 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  = more
    label  = More
    type   = char
    length = 4
    from_db= "MORE"
    url    = "$WDB/mydb/$form{'NAME'}/query/$val{'userid'}"
    computed
    forcetab
    no_query
    no_full

    FIELD  = userid 
    label  = Userid
    column = userid 
    type   = char			# char 
    length = 10
    key

    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 ( a full text is available from the contrib directory in the WDB distribution. )

    sub textohtml
        {
            local ( $str ) = @_;
            $str =~ s/\\ "{u}/ü/g;
            $str =~ s/\\ "{U}/Ü/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

Even if you can use WDB without writting any code at all, a lot of things can be done using the evaluated attributes in the FDF files. I hope the above simple examples have given you a taste of this. So to get the 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. A list is available at :

    http://www.eecs.nwu.edu/perl/perl.html