1 |
GEDAFE-USER(1) gedafe GEDAFE-USER(1) |
2 |
|
3 |
|
4 |
|
5 |
NAME |
6 |
gedafe-user - the Generic Database Front-End (Gedafe) |
7 |
User-Manual |
8 |
|
9 |
DESCRIPTION |
10 |
Gedafe (the Generic Database Front-End) is a web-based |
11 |
database front-end that is database-application indepen- |
12 |
dent. That means that the (perl) code doesn't contain any |
13 |
information about what tables are present in the database |
14 |
or how the data is organized. |
15 |
|
16 |
This is only possible if a full-featured SQL dB server |
17 |
like PostgreSQL is used as backend. PostgreSQL permits to |
18 |
define not only the format of the various tables and |
19 |
fields, but also how tables are related to each other. It |
20 |
is even possible to write powerful functions inside the |
21 |
database which get executed as new data is accessed or |
22 |
modified. Together, these features allow the implementa- |
23 |
tion of data integrity constraints inside the database |
24 |
itself. |
25 |
|
26 |
The effect of this is, that the database server guarantees |
27 |
the integrity of the database, independently from the |
28 |
software used to access the database. A front-end can read |
29 |
all the integrity constraints directly off the database |
30 |
and enforce them itself in order to provide faster |
31 |
response to the user, but at the end of the day the |
32 |
database server will only accept data which follow the |
33 |
rules defined by the database programmer. |
34 |
|
35 |
Overall, this approach makes the creation and maintenance |
36 |
of database applications much simpler. New databases can |
37 |
be created on the database server alone, using the lan- |
38 |
guage which is best suited for this task: SQL. The front- |
39 |
end then comes almost for free. |
40 |
|
41 |
Features |
42 |
|
43 |
Gedafe has the following features: |
44 |
|
45 |
o It is completely generic. Gedafe does not need to know |
46 |
anything about the structure or contents of the |
47 |
database it is working with. |
48 |
|
49 |
o Authentication is done at the database-level. |
50 |
|
51 |
o It is URL transparent. This means, you can directly |
52 |
access the URL of the page you want to look at. If |
53 |
necessary, the login screen will pop up and after a |
54 |
successful login you will be presented the page you |
55 |
initially requested. |
56 |
|
57 |
o Almost no HTML is used in the front-end code. External |
58 |
template files define the look and feel of pages. |
59 |
|
60 |
o POST is used only for data that modifies the database. |
61 |
Every page has a distinct URL, which makes them |
62 |
storable as bookmarks (Deep Linking). |
63 |
|
64 |
o Double form protection. The front-end prevents acci- |
65 |
dental repeated submission of the same form. This is |
66 |
implemented using a unique serial number for each |
67 |
form. |
68 |
|
69 |
o Using the PearlReports integration, is is possible to |
70 |
write custom multilevel report modules (Pearls) avail- |
71 |
able from the Gedafe webinterface. |
72 |
|
73 |
INSTALLATION |
74 |
The structure of the Gedafe distribution is as follows: |
75 |
|
76 |
. |
77 |
|-- bin/ binaries (gedafed daemon) |
78 |
|-- doc/ documentation |
79 |
|-- lib/ |
80 |
| `-- perl/ |
81 |
| |-- Gedafe/ gedafed main source |
82 |
| |-- DBIx/ PearlReports (required for gedafe pearls) |
83 |
| `-- Text/ CPPTemplates (required for gedafe screen layout) |
84 |
`-- example |
85 |
|-- templates/ HTML templates |
86 |
|-- mypearls/ Sample pearl report module |
87 |
|-- demo1.cgi demo-application script |
88 |
`-- demo1.sql PostgreSQL script to initialize the |
89 |
demo-application database |
90 |
|
91 |
In order to start using gedafe you must ensure that |
92 |
lib/perl of the Gedafe distribution is found by perl and |
93 |
start the gedafed daemon (you can use the script gedafed- |
94 |
ctl to start it with SYSV-init). |
95 |
|
96 |
The Application Script |
97 |
|
98 |
Gedafe is actually a library. The application itself just |
99 |
calls the 'Start' function of the library, providing the |
100 |
necessary configuration information as arguments. The |
101 |
application startup script should look as follows: |
102 |
|
103 |
#!/usr/sepp/bin/speedy -w |
104 |
|
105 |
use lib "/usr/local/gedafe/lib/perl"; |
106 |
|
107 |
use Gedafe::Start; |
108 |
|
109 |
Start( |
110 |
db_datasource => 'dbi:Pg:dbname=demo', |
111 |
list_rows => 15, |
112 |
templates => '/usr/local/gedafe/templates/demo', |
113 |
documentation_url => 'http://mysite.com/demo-docs', |
114 |
show_row_count => 1, |
115 |
isearch => '/place/in/the/webtree/for/isearch.jar', |
116 |
pearl_dir => '/usr/local/gedafe/example/mypearls', |
117 |
list_buttons => 'both', |
118 |
); |
119 |
|
120 |
Gedafe gathers information about the database structure |
121 |
when it is started. This process can take a lot of time, |
122 |
it is therefor strongly suggested that you use a persis- |
123 |
tent perl instance, for example speedy. mod_perl works |
124 |
also great, but you have to be careful if you run multiple |
125 |
database applications, since if the same persistent perl |
126 |
is used, the cached data of the applications will go in |
127 |
the same global variables, which is certainly not what you |
128 |
want. |
129 |
|
130 |
Of course, you must specify the correct path name to your |
131 |
perl interpreter in the first line of the script (unless |
132 |
you use a webserver perl module). |
133 |
|
134 |
Very important in this script is the first 'use' state- |
135 |
ment. It should point to where you have stored lib/perl of |
136 |
the distribution. Start starts the application by specify- |
137 |
ing Gedafe configuration variables. The following configu- |
138 |
ration variables are defined: |
139 |
|
140 |
db_datasource DBI data-source string specifying the |
141 |
database. |
142 |
|
143 |
list_rows Default number of rows to show. |
144 |
|
145 |
templates The directory where the html templates |
146 |
are stored (you can use a copy exam- |
147 |
ple/templates as a basis for you local |
148 |
modifications). |
149 |
|
150 |
documentation_url URL passed to the html templates where |
151 |
the documentation of the application |
152 |
is stored. |
153 |
|
154 |
show_row_count Options: [0,1] If set, show a count of |
155 |
total records returned by each select, |
156 |
along with extra navigation links to |
157 |
skip to first and last pages of result |
158 |
set. Since this produces slightly |
159 |
higher database overhead (an added |
160 |
SELECT COUNT(*) for every SELECT), it |
161 |
is turned off by default. |
162 |
|
163 |
isearch Web-servers don't like Java archives |
164 |
(jar) to be down-loaded from cgi-bin |
165 |
directory's. They will try to execute |
166 |
them instead. To resolve this, you |
167 |
have to place the 'incremental search |
168 |
widget' (isearch) Java archive in a |
169 |
place where it can be down-loaded like |
170 |
any other file. This item is used to |
171 |
point gedafe to the place where you |
172 |
have put the isearch.jar. Please make |
173 |
sure that it is on the same server and |
174 |
preferably a relative address. Java |
175 |
security restrictions require this. |
176 |
|
177 |
list_buttons Options: ['top','bot- |
178 |
tom','both','none'] This option acts |
179 |
on the buttons that appear with table |
180 |
or view lists, the first,previ- |
181 |
ous,add,next,last buttons. Top |
182 |
selects only buttons above the list. |
183 |
Bottom selects only buttons below the |
184 |
list. None removes all buttons, but |
185 |
doing so wouldn't make much sense. |
186 |
When omitted the default is 'both'. |
187 |
|
188 |
pearl_dir Name of a directory where gedafe |
189 |
should go looking for pearls. Pearls |
190 |
are object oriented perl modules which |
191 |
first display a data input screen and |
192 |
then run a report off the database |
193 |
based on the entires given at the data |
194 |
entry screen. See gedafe-pearls.pod |
195 |
for more information. |
196 |
|
197 |
|
198 |
|
199 |
|
200 |
The gedafed Daemon |
201 |
|
202 |
Gedafe uses an external process called gedafed to manage |
203 |
session data. This daemon must be running to make Gedafe |
204 |
work. You can start it during the boot process of your |
205 |
server using the bin/gedafed-ctl script. |
206 |
|
207 |
The Database |
208 |
|
209 |
gedafe-sql.pod describes how the database should be setup |
210 |
to work with Gedafe. |
211 |
|
212 |
USAGE |
213 |
Authentication |
214 |
|
215 |
Authentication is done with the help of gedafed. This dae- |
216 |
mon stores user/password pairs using a random-generated |
217 |
"ticket", which is stored in a cookie on the client side. |
218 |
To make these tickets more secure gedafed manages an expi- |
219 |
ration on these tickets. Every time that ticket is used, |
220 |
it's expiration is prolonged by a certain amount of sec- |
221 |
onds (configured in the script). If the database isn't |
222 |
accessed for a certain amount of time, the ticket is |
223 |
expired and a new login must be made. |
224 |
|
225 |
The login screen is transparent to the page accessed: |
226 |
whenever a login is needed, the login screen is first pre- |
227 |
sented, after which the requested page is shown. |
228 |
|
229 |
Warning: Gedafe will not work with blank passwords. If you |
230 |
want to do anonymous logins, you may put the user in the |
231 |
url (as an additional parameter, user=xxx&...) and the |
232 |
password sent to the database will be 'anonymous'. |
233 |
|
234 |
Forms and Navigation |
235 |
|
236 |
The navigation and general use of Gedafe should be |
237 |
straightforward. At the beginning, you are presented with |
238 |
the "Entry" page that contains links to every table to |
239 |
edit and to every available report. |
240 |
|
241 |
For forms, the guiding principle while designing Gedafe |
242 |
was 'POST is evil, use it the least possible'. The reason |
243 |
for it is that if a generated page depends on POST data, |
244 |
that page can't be stored in a bookmark and the browsers |
245 |
have problems handling the reloading of pages obtained |
246 |
with a POST request. For that reason, POST was used only |
247 |
for database-modifying actions where large amounts of data |
248 |
must be transferred. |
249 |
|
250 |
HTML Layout |
251 |
|
252 |
Almost no HTML is used in the perl code. The HTML is gen- |
253 |
erated with the help of Text::CPPTemplate, a very simple |
254 |
C-preprocessor-style templating system included in the |
255 |
Gedafe distribution. The templates are taken from a direc- |
256 |
tory specified in the startup script with the 'templates' |
257 |
parameter. |
258 |
|
259 |
The basic idea is that Gedafe places small "elements" of |
260 |
the page currently being generated such as the header or |
261 |
the cell of a table by only specifying variables (proper- |
262 |
ties) of that element. Every element has always the fol- |
263 |
lowing minimal variables specified: |
264 |
|
265 |
PAGE Name of the page (for example login, entry or |
266 |
list). |
267 |
|
268 |
ELEMENT Name of the element (for example header or td). |
269 |
|
270 |
In addition, element-specific data such as DATA for the td |
271 |
element must be defined. Text::CPPTemplate will then |
272 |
search for an appropriate template to use and generate the |
273 |
HTML code. See Text::CPPTemplate(3) for a description of |
274 |
the syntax and how the templates are stored in files. See |
275 |
also gedafe-templates.txt for a description of what ele- |
276 |
ments are used with what variables. |
277 |
|
278 |
Hidden features |
279 |
|
280 |
|
281 |
o In the URL: "list_rows=nn" override the number-of-dis- |
282 |
played-rows specified in the startup script. |
283 |
|
284 |
o In the URL: "theme=xxx" set the theme (templates will |
285 |
be loaded from that subdirectory of the templates |
286 |
directory) |
287 |
|
288 |
o In the URL: "reload=1" reset all the cached data. This |
289 |
is useful, for example, if you changed a template file |
290 |
or the structure of the database. |
291 |
|
292 |
o "today" or "yesterday" can be specified as search |
293 |
value for a 'Date' field. |
294 |
|
295 |
o Numbers can be entered as "hh:mm" (for example |
296 |
"0:10"). The "mm" part will be multiplied by 100/60 |
297 |
and added to "hh". |
298 |
|
299 |
o Some supporting perl modules are auto-detected and |
300 |
only used if they are installed on the system gedafe |
301 |
is running on. These are currently: |
302 |
|
303 |
- Text::CSV_XS : for exporting data as comma-sepa- |
304 |
rated value (CSV) format; if not installed, only |
305 |
the default tab-delimited format will be available |
306 |
for exporting data. |
307 |
|
308 |
Caching and Bookmarks |
309 |
|
310 |
A difficulty that we encountered while developing Gedafe |
311 |
was the caching of pages by the browser. We have to con- |
312 |
trol precisely when a page can be cached and when not. The |
313 |
implementation is made with the "refresh" URL parameter: |
314 |
when it is set, the expiration of the page is set to some |
315 |
positive value, meaning that the page can be cached. If |
316 |
"refresh" is not available, the expiration is negative, |
317 |
meaning that the page should not be cached. The value of |
318 |
"refresh" is a random number, that can be changed to force |
319 |
a reload of the page. |
320 |
|
321 |
A side-effect of this technique is that pages with |
322 |
"refresh" in the URL are not suitable to be stored as |
323 |
bookmarks, since you would then get always the same cached |
324 |
version. For that reason, bookmarks should be always saved |
325 |
without the "refresh" parameter, such that a new version |
326 |
of the page is always requested from the server. There is |
327 |
a link on every page, that you can drag to store the cur- |
328 |
rently viewed page. |
329 |
|
330 |
TROUBLESHOOTING |
331 |
Edit form is empty |
332 |
|
333 |
When you get an empty form after selecting 'Edit' for a |
334 |
record, this could mean that you didn't put the record |
335 |
*_id into the first column of the presentation (*_list) |
336 |
view or the table (if there isn't a presentation view). |
337 |
Gedafe must know the id of the record to edit and it does |
338 |
so by using the first column as key. See the |
339 |
gedafe-sql.pod, section 'Presentation View'. |
340 |
|
341 |
SEE ALSO |
342 |
gedafe-sql.pod, gedafe-templates.txt, Text::CPPTemplate, |
343 |
gedafe-pearls.pod, DBIx::PearlReports |
344 |
|
345 |
COPYRIGHT |
346 |
Copyright (c) 2000-2003 ETH Zurich, All rights reserved. |
347 |
|
348 |
LICENSE |
349 |
This program is free software; you can redistribute it |
350 |
and/or modify it under the terms of the GNU General Public |
351 |
License as published by the Free Software Foundation; |
352 |
either version 2 of the License, or (at your option) any |
353 |
later version. |
354 |
|
355 |
This program is distributed in the hope that it will be |
356 |
useful, but WITHOUT ANY WARRANTY; without even the implied |
357 |
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR |
358 |
PURPOSE. See the GNU General Public License for more |
359 |
details. |
360 |
|
361 |
You should have received a copy of the GNU General Public |
362 |
License along with this program; if not, write to the Free |
363 |
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA |
364 |
02139, USA. |
365 |
|
366 |
AUTHOR |
367 |
Tobias Oetiker <oetiker@ee.ethz.ch>, David Schweik- |
368 |
ert <dws@ee.ethz.ch>, Fritz Zaucker <zaucker@ee.ethz.ch>, |
369 |
Adi Fairbank <adi@adiraj.org>, Freek Zindel <freek@zin- |
370 |
del.nl> |
371 |
|
372 |
|
373 |
|
374 |
1.2.2 2003-09-22 GEDAFE-USER(1) |