/[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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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)

  ViewVC Help
Powered by ViewVC 1.1.26