trunk/doc/gedafe-user.txt

GEDAFE-USER(1)                gedafe               GEDAFE-USER(1)


NAME
       gedafe-user - the Generic Database Front-End (Gedafe)
       User-Manual

DESCRIPTION
       Gedafe (the Generic Database Front-End) is a web-based
       database front-end that is database-application indepen-
       dent. That means that the (perl) code doesn't contain any
       information about what tables are present in the database
       or how the data is organized.

       This is only possible if a full-featured SQL dB server
       like PostgreSQL is used as backend. PostgreSQL permits to
       define not only the format of the various tables and
       fields, but also how tables are related to each other. It
       is even possible to write powerful functions inside the
       database which get executed as new data is accessed or
       modified. Together, these features allow the implementa-
       tion of data integrity constraints inside the database
       itself.

       The effect of this is, that the database server guarantees
       the integrity of the database, independently from the
       software used to access the database. A front-end can read
       all the integrity constraints directly off the database
       and enforce them itself in order to provide faster
       response to the user, but at the end of the day the
       database server will only accept data which follow the
       rules defined by the database programmer.

       Overall, this approach makes the creation and maintenance
       of database applications much simpler. New databases can
       be created on the database server alone, using the lan-
       guage which is best suited for this task: SQL. The front-
       end then comes almost for free.

       Features

       Gedafe has the following features:

       o   It is completely generic. Gedafe does not need to know
           anything about the structure or contents of the
           database it is working with.

       o   Authentication is done at the database-level.

       o   It is URL transparent.  This means, you can directly
           access the URL of the page you want to look at. If
           necessary, the login screen will pop up and after a
           successful login you will be presented the page you
           initially requested.

       o   Almost no HTML is used in the front-end code. External
           template files define the look and feel of pages.

       o   POST is used only for data that modifies the database.
           Every page has a distinct URL, which makes them
           storable as bookmarks (Deep Linking).

       o   Double form protection. The front-end prevents acci-
           dental repeated submission of the same form. This is
           implemented using a unique serial number for each
           form.

       o   Using the PearlReports integration, is is possible to
           write custom multilevel report modules (Pearls) avail-
           able from the Gedafe webinterface.

INSTALLATION
       The structure of the Gedafe distribution is as follows:

        .
        |-- bin/             binaries (gedafed daemon)
        |-- doc/             documentation
        |-- lib/
        |   `-- perl/
        |       |-- Gedafe/  gedafed main source
        |       |-- DBIx/    PearlReports (required for gedafe pearls)
        |       `-- Text/    CPPTemplates (required for gedafe screen layout)
        `-- example
            |-- templates/   HTML templates
            |-- mypearls/    Sample pearl report module
            |-- demo1.cgi    demo-application  script
            `-- demo1.sql    PostgreSQL script to initialize the
                             demo-application database

       In order to start using gedafe you must ensure that
       lib/perl of the Gedafe distribution is found by perl and
       start the gedafed daemon (you can use the script gedafed-
       ctl to start it with SYSV-init).

       The Application Script

       Gedafe is actually a library. The application itself just
       calls the 'Start' function of the library, providing the
       necessary configuration information as arguments. The
       application startup script should look as follows:

        #!/usr/sepp/bin/speedy -w

        use lib "/usr/local/gedafe/lib/perl";

        use Gedafe::Start;

        Start(
               db_datasource  => 'dbi:Pg:dbname=demo',
               list_rows      => 15,
               templates      => '/usr/local/gedafe/templates/demo',
               documentation_url => 'http://mysite.com/demo-docs',
               show_row_count => 1,
               isearch        => '/place/in/the/webtree/for/isearch.jar',
               pearl_dir      => '/usr/local/gedafe/example/mypearls',
               list_buttons   => 'both',
        );

       Gedafe gathers information about the database structure
       when it is started.  This process can take a lot of time,
       it is therefor strongly suggested that you use a persis-
       tent perl instance, for example speedy. mod_perl works
       also great, but you have to be careful if you run multiple
       database applications, since if the same persistent perl
       is used, the cached data of the applications will go in
       the same global variables, which is certainly not what you
       want.

       Of course, you must specify the correct path name to your
       perl interpreter in the first line of the script (unless
       you use a webserver perl module).

       Very important in this script is the first 'use' state-
       ment. It should point to where you have stored lib/perl of
       the distribution. Start starts the application by specify-
       ing Gedafe configuration variables. The following configu-
       ration variables are defined:

       db_datasource       DBI data-source string specifying the
                           database.

       list_rows           Default number of rows to show.

       templates           The directory where the html templates
                           are stored (you can use a copy exam-
                           ple/templates as a basis for you local
                           modifications).

       documentation_url   URL passed to the html templates where
                           the documentation of the application
                           is stored.

       show_row_count      Options: [0,1] If set, show a count of
                           total records returned by each select,
                           along with extra navigation links to
                           skip to first and last pages of result
                           set.  Since this produces slightly
                           higher database overhead (an added
                           SELECT COUNT(*) for every SELECT), it
                           is turned off by default.

       isearch             Web-servers don't like Java archives
                           (jar) to be down-loaded from cgi-bin
                           directory's. They will try to execute
                           them instead. To resolve this, you
                           have to place the 'incremental search
                           widget' (isearch) Java archive in a
                           place where it can be down-loaded like
                           any other file.  This item is used to
                           point gedafe to the place where you
                           have put the isearch.jar. Please make
                           sure that it is on the same server and
                           preferably a relative address. Java
                           security restrictions require this.

       list_buttons        Options: ['top','bot-
                           tom','both','none'] This option acts
                           on the buttons that appear with table
                           or view lists, the first,previ-
                           ous,add,next,last buttons.  Top
                           selects only buttons above the list.
                           Bottom selects only buttons below the
                           list.  None removes all buttons, but
                           doing so wouldn't make much sense.
                           When omitted the default is 'both'.

       pearl_dir           Name of a directory where gedafe
                           should go looking for pearls. Pearls
                           are object oriented perl modules which
                           first display a data input screen and
                           then run a report off the database
                           based on the entires given at the data
                           entry screen. See gedafe-pearls.pod
                           for more information.


       The gedafed Daemon

       Gedafe uses an external process called gedafed to manage
       session data. This daemon must be running to make Gedafe
       work. You can start it during the boot process of your
       server using the bin/gedafed-ctl script.

       The Database

       gedafe-sql.pod describes how the database should be setup
       to work with Gedafe.

USAGE
       Authentication

       Authentication is done with the help of gedafed. This dae-
       mon stores user/password pairs using a random-generated
       "ticket", which is stored in a cookie on the client side.
       To make these tickets more secure gedafed manages an expi-
       ration on these tickets. Every time that ticket is used,
       it's expiration is prolonged by a certain amount of sec-
       onds (configured in the script).  If the database isn't
       accessed for a certain amount of time, the ticket is
       expired and a new login must be made.

       The login screen is transparent to the page accessed:
       whenever a login is needed, the login screen is first pre-
       sented, after which the requested page is shown.

       Warning: Gedafe will not work with blank passwords. If you
       want to do anonymous logins, you may put the user in the
       url (as an additional parameter, user=xxx&...) and the
       password sent to the database will be 'anonymous'.

       Forms and Navigation

       The navigation and general use of Gedafe should be
       straightforward. At the beginning, you are presented with
       the "Entry" page that contains links to every table to
       edit and to every available report.

       For forms, the guiding principle while designing Gedafe
       was 'POST is evil, use it the least possible'. The reason
       for it is that if a generated page depends on POST data,
       that page can't be stored in a bookmark and the browsers
       have problems handling the reloading of pages obtained
       with a POST request. For that reason, POST was used only
       for database-modifying actions where large amounts of data
       must be transferred.

       HTML Layout

       Almost no HTML is used in the perl code. The HTML is gen-
       erated with the help of Text::CPPTemplate, a very simple
       C-preprocessor-style templating system included in the
       Gedafe distribution. The templates are taken from a direc-
       tory specified in the startup script with the 'templates'
       parameter.

       The basic idea is that Gedafe places small "elements" of
       the page currently being generated such as the header or
       the cell of a table by only specifying variables (proper-
       ties) of that element. Every element has always the fol-
       lowing minimal variables specified:

       PAGE      Name of the page (for example login, entry or
                 list).

       ELEMENT   Name of the element (for example header or td).

       In addition, element-specific data such as DATA for the td
       element must be defined. Text::CPPTemplate will then
       search for an appropriate template to use and generate the
       HTML code. See Text::CPPTemplate(3) for a description of
       the syntax and how the templates are stored in files. See
       also gedafe-templates.txt for a description of what ele-
       ments are used with what variables.

       Hidden features


       o   In the URL: "list_rows=nn" override the number-of-dis-
           played-rows specified in the startup script.

       o   In the URL: "theme=xxx" set the theme (templates will
           be loaded from that subdirectory of the templates
           directory)

       o   In the URL: "reload=1" reset all the cached data. This
           is useful, for example, if you changed a template file
           or the structure of the database.

       o   "today" or "yesterday" can be specified as search
           value for a 'Date' field.

       o   Numbers can be entered as "hh:mm" (for example
           "0:10"). The "mm" part will be multiplied by 100/60
           and added to "hh".

       o   Some supporting perl modules are auto-detected and
           only used if they are installed on the system gedafe
           is running on.  These are currently:

           -   Text::CSV_XS : for exporting data as comma-sepa-
               rated value (CSV) format; if not installed, only
               the default tab-delimited format will be available
               for exporting data.

       Caching and Bookmarks

       A difficulty that we encountered while developing Gedafe
       was the caching of pages by the browser.  We have to con-
       trol precisely when a page can be cached and when not. The
       implementation is made with the "refresh" URL parameter:
       when it is set, the expiration of the page is set to some
       positive value, meaning that the page can be cached. If
       "refresh" is not available, the expiration is negative,
       meaning that the page should not be cached. The value of
       "refresh" is a random number, that can be changed to force
       a reload of the page.

       A side-effect of this technique is that pages with
       "refresh" in the URL are not suitable to be stored as
       bookmarks, since you would then get always the same cached
       version. For that reason, bookmarks should be always saved
       without the "refresh" parameter, such that a new version
       of the page is always requested from the server. There is
       a link on every page, that you can drag to store the cur-
       rently viewed page.

TROUBLESHOOTING
       Edit form is empty

       When you get an empty form after selecting 'Edit' for a
       record, this could mean that you didn't put the record
       *_id into the first column of the presentation (*_list)
       view or the table (if there isn't a presentation view).
       Gedafe must know the id of the record to edit and it does
       so by using the first column as key. See the
       gedafe-sql.pod, section 'Presentation View'.

SEE ALSO
       gedafe-sql.pod, gedafe-templates.txt, Text::CPPTemplate,
       gedafe-pearls.pod, DBIx::PearlReports

COPYRIGHT
       Copyright (c) 2000-2003 ETH Zurich, All rights reserved.

LICENSE
       This program is free software; you can redistribute it
       and/or modify it under the terms of the GNU General Public
       License as published by the Free Software Foundation;
       either version 2 of the License, or (at your option) any
       later version.

       This program is distributed in the hope that it will be
       useful, but WITHOUT ANY WARRANTY; without even the implied
       warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU General Public License for more
       details.

       You should have received a copy of the GNU General Public
       License along with this program; if not, write to the Free
       Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
       02139, USA.

AUTHOR
       Tobias Oetiker <oetiker@ee.ethz.ch>, David Schweik-
       ert <dws@ee.ethz.ch>, Fritz Zaucker <zaucker@ee.ethz.ch>,
       Adi Fairbank <adi@adiraj.org>, Freek Zindel <freek@zin-
       del.nl>


1.2.2                       2003-09-22             GEDAFE-USER(1)
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)