PREV TOC

template files

dbengine is able to create the HTML representation of your database on the fly, but you might rather want to create the pages on your own to meet your personal design ideas.

That is where template files come into place. You might remember that you've already specified a directory where those files reside in the configuration section of this documentation.

Using template files is pretty straight forward. Simply create a HTML file named after the table which it shall be used for (with extension .html) and store it in your template directory.
dbengine will look for such a file before it generates its HTML output and if it finds your template there will be no more automatic page generation.

A template file for our test database articles would be names articles.html and stored in the template directory.

dbengines substitution

If a template file is found for a table and you've asked dbengine to display an already existing record, the tool will add VALUE tags after each NAME tag which corresponds to an existing fieldname, so that your Web browser will show the contents of the selected record.
If you're using a TEXTAREA the contents will be inserted at the appropriate place between the start and end tag.

This feature will only work in case you DON'T USE ANY VALUE-TAGS IN YOUR FORMS.

Any server side includes will be executed and their calls substituted by their results.

embedded Perl code

At any place you may use special comments beginning with
<--**
and ending with
-->
to insert Perl code into your Web pages.
dbengine will interpret the text between these special comment tags as a Perl script and try to evaluate it. The comment then is replaces with either a Perl error message or the return value of your code.

useful methods and variables

Within any Perl code you have full access to the dbengine source, the CGI and Postgres libraries.
Especially all the variables specified in the beginning of the dbengine source are available, of which the most important ones are:
variable type use
$query CGI $query is initialized with the arguments from the last call of our CGI
$table char the name of the table we're currently working with
$conn DBI Database handle to our main database (where $table lives)
$dconn DBI Database handle to our description database
%values associative array If a record has been opened for display this array will contain all it's fields, so that you can access a fields value by $values{'nameOfField'}.
This is also true for virtual Fields.

There are also some useful routines available that make live easier:
name arguments use
callDBaseSub $theName, $arguments callDBaseSub scans the equation database for an entry with name $theName and executes its code which is given all further $arguments.
If there occurs any error $@ is set to the error message and undef is returned. Otherwise the routine returns whatever value the last expression of our routine has.
valueListPopup fieldName creates a simple HTML popup menu with name $name that displays all the values specified in the valuelist table of our display description database for this specific fieldName.
relationPopup $name, $relTable, $relField creates a simple HTML popup menu with name $name that displays all the different values in $relField from table $relTable in the main database
tablePopup $name creates a simple HTML popup with name $name menu that displays all available tables in the main database
xChop $aString xChop returns the given $aString without any training blanks

Restrictions

Due to the line-by line parsing method used to scan through your template files you're currently restricted to put all your FORM tags, server side include command, textareas and embedded Perl code in a single line each.
Feel free to modify the &scanAndReplaceTemplate routine and mail me a copy ;-)

Samples

Here are some HTML code snippets you can use in your template files.

This modified FORM ACTION should be used to make sure that dbengine.cgi will always be found:

METHOD="POST">

This one will be replaced by :

<--**&valueListPopup('category');-->

Here we get a representation of our cheapest price (if used in the sample articles table):

<--**$values{'cheapest'};-->

countries.html

This is about the smallest sample possible to illustrate the format of such a template file.
The file has to be saved in the specified templates directory and is used to desplay detail information for a table called "countries". Therefore the file has to be named "countries.html". Also this sample file only accesses a single field in that table which is called "country".

<HTML> <HEAD></HEAD> <BODY> <CENTER><H1>Country Data</H1><CENTER> <FORM ACTION=<--** "\"".$cgis."dbengine.cgi\"" --> METHOD="POST"> <P> Country:<br> <TEXTAREA NAME="country" ROWS=10 COLS=45></TEXTAREA> <P> <INPUT TYPE="submit" NAME="mode" VALUE="add"> <INPUT TYPE="submit" NAME="mode" VALUE="update"> <INPUT TYPE="submit" NAME="mode" VALUE="search"> <INPUT TYPE="submit" NAME="mode" VALUE="delete"> </FORM> </BODY> </HTML>

PREV TOC