1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
<HTML><HEAD>
<TITLE>dbengines template files</TITLE>
</HEAD>
<BODY>
<A HREF="descdbase.html"><IMG SRC="images/prev.gif" ALT="PREV"></A>
<A HREF="index.html"><IMG SRC="images/toc.gif" ALT="TOC"></A>
<P>
<H2>template files</H2>
<B>dbengine</B> 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.
<P>
That is where <I>template files</I> come into place. You might remember that you've already specified a directory where those files reside in the <A HREF="configuration.html#template">configuration section</A> of this documentation.<P>
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. <BR>
<B>dbengine</B> 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.<P>
A template file for our test database articles would be names articles.html and stored in the template directory.
<H3><B>dbengine</B>s substitution</H3>
If a template file is found for a table and you've asked <B>dbengine</B> 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.<BR>
If you're using a TEXTAREA the contents will be inserted at the appropriate place between the start and end tag.
<P>
<B>This feature will only work in case you DON'T USE ANY VALUE-TAGS IN YOUR FORMS.</B><P>
Any server side includes will be executed and their calls substituted by their results.
<P>
<H3>embedded Perl code</H3>
At any place you may use special comments beginning with <PRE><--**</PRE> and ending with <PRE>--></PRE> to insert Perl code into your Web pages.<BR>
<B>dbengine</B> 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.
<H4>useful methods and variables</H4>
Within any Perl code you have full access to the <B>dbengine</B> source, the CGI and Postgres libraries.<BR>
Especially all the variables specified in the beginning of the <B>dbengine</B> source are available, of which the
most important ones are:
<TABLE>
<TR>
<TD><B>variable</B>
<TD><B>type</B>
<TD><B>use</B>
<TR>
<TD>$query
<TD>CGI
<TD>$query is initialized with the arguments from the last call of our CGI
<TR>
<TD>$table
<TD>char
<TD>the name of the table we're currently working with
<TR>
<TD>$conn
<TD>DBI
<TD>Database handle to our main database (where $table lives)
<TR>
<TD>$dconn
<TD>DBI
<TD>Database handle to our description database
<TR>
<TD>%values
<TD>associative array
<TD>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'}.<BR>
This is also true for virtual Fields.
</TABLE>
<P>
There are also some useful routines available that make live easier:
<TABLE>
<TR>
<TD><B>name</B>
<TD><B>arguments</B>
<TD><B>use</B>
<TR>
<TD>callDBaseSub
<TD>$theName, $arguments
<TD>callDBaseSub scans the equation database for an entry with name <I>$theName</I> and executes its code
which is given all further <I>$arguments</I>.<BR>
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.
<TR>
<TD>valueListPopup
<TD>fieldName
<TD>creates a simple HTML popup menu with name <I>$name</I> that displays all the values specified in the
valuelist table of our display description database for this specific <I>fieldName</I>.
<TR>
<TD>relationPopup
<TD>$name, $relTable, $relField
<TD>creates a simple HTML popup menu with name <I>$name</I> that displays all the different values in <I>$relField</I>
from table <I>$relTable</I> in the main database
<TR>
<TD>tablePopup
<TD>$name
<TD>creates a simple HTML popup with name <I>$name</I> menu that displays all available tables in the main database
<TR>
<TD>xChop
<TD>$aString
<TD>xChop returns the given <I>$aString</I> without any training blanks
</TABLE>
<H3>Restrictions</H3>
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.<BR>
Feel free to modify the &scanAndReplaceTemplate routine and mail me a copy ;-)
<H3>Samples</H3>
Here are some HTML code snippets you can use in your template files.<P>
This modified FORM ACTION should be used to make sure that dbengine.cgi will always be found:
<PRE>
<FORM ACTION= <--** if($cgis) { "\"".$cgis."dbengine.cgi\"" . " TARGET=body "; } else { "\"dbengine.cgi\""; } --> METHOD="POST">
</PRE>
<P>This one will be replaced by <SELECT NAME="category" SIZE=1>
<OPTION>
<OPTION>hardware
<OPTION>software
</SELECT>
:
<PRE>
<--**&valueListPopup('category');-->
</PRE>
<P>Here we get a representation of our cheapest price (if used in the sample articles table):
<PRE>
<--**$values{'cheapest'};-->
</PRE>
<H3>countries.html</H3>
<P>This is about the smallest sample possible to illustrate the format of such a template file.
<BR>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".
<PRE><p>
<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>
</p></PRE>
<P>
<A HREF="descdbase.html"><IMG SRC="images/prev.gif" ALT="PREV"></A>
<A HREF="index.html"><IMG SRC="images/toc.gif" ALT="TOC"></A>
</BODY>
</HTML>
|
