1 |
dpavlin |
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) |