 |
|
|||
 |
||||
|
||||
           Last Update: 2003-09-29 |
|
 NAMEgedafe-user - the Generic Database Front-End (Gedafe) User-Manual DESCRIPTIONGedafe (the Generic Database Front-End) is a web-based database front-end that is database-application independent. 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 implementation 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 language which is best suited for this task: SQL. The front-end then comes almost for free. FeaturesGedafe has the following features:
INSTALLATIONThe 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 ScriptGedafe 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:
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',
oyster_dir => '/usr/local/gedafe/example/myoysters',
list_buttons => 'both',
edit_buttons_left => 1,
file2fs_dir => '/var/gedafe/upload_dir',
);
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 persistent 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' statement. It should point to where you have stored lib/perl of the distribution. Start starts the application by specifying Gedafe configuration variables. The following configuration variables are defined:
The gedafed DaemonGedafe 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 Databasegedafe-sql.pod describes how the database should be setup to work with Gedafe. USAGEAuthenticationAuthentication is done with the help of gedafed. This daemon 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 expiration on these tickets. Every time that ticket is used, it's expiration is prolonged by a certain amount of seconds (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 presented, 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 NavigationThe 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. SearchingYou can search on multiple fields, which are represented in the list view as multiple text fields on different lines. Each field must match. In each of the fields, you can type a search term using the following syntax:
Further, you can also join such expressions with 'OR' and 'AND. For example: > 2004-01-01 and < 2004-12-31 HTML LayoutAlmost no HTML is used in the perl code. The HTML is generated 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 directory 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 (properties) of that element. Every element has always the following minimal variables specified:
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 the Text::CPPTemplate(3) manpage for a description of the syntax and how the templates are stored in files. See also gedafe-templates.txt for a description of what elements are used with what variables. Postgres Schema supportIt is possible to use schema support if Postgres is Version 7.2 or newer. For database versions < 7.2 schema support is disabled. No test have be done yet if Postgres versions < 7.2 really work after introdution of schema support. A schema is a group of tables in postgres. You can order your tables by moving them in several schemas without changing views and select statements. If you add more then one schema to your gedafe application, the top of the Entry screen shows links into the other schemas instead of table links. Schema support is activated with 2 optional config parameters for Start.pm. These values are:
Syntax: A comma separated list of single quoted schema names like ``'public','test''. Is ignored, if schema is not set. Defines the group of schemas we want to make accesible for gedafe. To be exact, all tables are acessible by prefixing their schema name (e.g. testschema.testtable is table testtable in schema testschema). You can use schema prefixes in sql commands, e.g. in views. But gedafe itself does not prefix table names. To reference tables from more then the 'public' schema, we have to put the schema names in a schema_search_path. When setting a schema_search_path, you only will see links for tables in the ``actual'' schema but you can access all tables within the search path by their names as if they were in the current schema. CAVEAT: Beware of name collisions. Never put 2 tables with the same name in two schemas (inside your search path), as the results can be hard to predict. Also always put 'public' in your schema search path. Put the tables meta_fields and meta_tables in the 'public' schema. The effects of having several meta_fields and meta_tables will be hard to predict. =head2 Hidden features
Caching and BookmarksA difficulty that we encountered while developing Gedafe was the caching of pages by the browser. We have to control precisely when a page can be cached and when not. The implementation is made with the A side-effect of this technique is that pages with TROUBLESHOOTINGEdit form is emptyWhen 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 ALSOgedafe-sql.pod, gedafe-templates.txt, Text::CPPTemplate, gedafe-pearls.pod, DBIx::PearlReports COPYRIGHTCopyright (c) 2000-2003 ETH Zurich, All rights reserved. LICENSEThis 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. AUTHORTobias Oetiker, David Schweikert, Fritz Zaucker, Adi Fairbank, Freek Zindel |
|
|
|
||||
