/[gedafe]/trunk/doc/gedafe-user.txt
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /trunk/doc/gedafe-user.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (show annotations)
Mon Feb 14 18:52:26 2005 UTC (14 years, 8 months ago) by dpavlin
File MIME type: text/plain
File size: 16184 byte(s)
import of Gedafe 1.2.2

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)

  ViewVC Help
Powered by ViewVC 1.1.26