== README for YAPfront 0.1.0alpha2 ==
 
 
 1. Overview
 -----------
 
 YAPfront is - Yet Another PostgreSQL Frontend. It is aimed to provide
 a easy to use web frontend to a PostgreSQL database, rather for
 intranet than internet. It is not made for the administrator or
 developer but for the user. With this version of YAPfront only a
 single table can be used for editing (what has to change in the
 future). Since PostgreSQL is a very powerful database management
 system providing triggers and stored procedures, it should be possible
 to map nearly every database to a single table for editing. A
 arbitrary number of views can be browsed additionally. Supported
 features are: easy search by regular expressions, extended search,
 customization using templates and stylesheets, different kinds of
 authentication, extension via hook functions aka callbacks and a lot
 more. Typical use cases for YAPfront might be a address book, a
 customer database or a text library. Multiple setups for multiple use
 cases may have access to the same installation of the classes on a
 server. The user adminisration is maintained by PostgreSQL, not by
 YAPfront.
 
 
 
 
 2. Prerequisites
 ----------------
 
 PHP >= 4.1.2 (pcre, pgsql, mcrypt)
 PostgreSQL >= 7.2.1
 
 
 
 3. Installation
 ----------------
 
 3.1. What you need for Installation
 
 Required:
 
 - a running webserver with PHP support
 - a running and accessible PostgreSQL server (the server may
   run on a remote mashine)
 - username/password for the server
 - the privilege to create a database on the server
 - pg_restore on the mashine where you run the installation
 - write access to DOCUMENT_ROOT
 
 Optional:
 
 - (GNU) Make
 
 
 
 3.2. Installation using GNU Make
 
 After unpacking the archive you may use GNU Make (or any compatible
 make tool) to install all necessary files. The tool pg_restore should
 be in the PATH.
 
   make install PGHOST=[mashine.wherepostgres.runs] \
                PGUSER=[username] \
                PGPORT=[number] \
                DOCROOT=[/your/document/root]
                INSTALLDIR=[/dir/below/docroot]
 
 If you omit one of the variables, the default value will be used:
 
   PGHOST=localhost
   PGUSER=root
   PGPORT=5432
   DOCROOT=.
   INSTALLDIR=/YAPfront
 
 Note: The installation process will prompt you for a valid PostgreSQL
 password.
 
 
 
 3.3. Installation with cp and pg_restore
 
 1. cp -a ./class ./setup ./tmpl [/your/docroot/YAPfront]
 
 2. cd ./data.help
 
 3. pg_restore -C -U [username]                \
               -d template1                    \
               -h [mashine.wherepostgres.runs] \
               YAPfront-help.tar
 
 
 
 4. Testing the installation
 ---------------------------
 
 1. open your web browser (e.g. Mozilla)
 
 2. enable cookies
 
 3. point your browser to http://webserver.your.domain/YAPfront/help.php
 
 4. type your PostgreSQL username and password
 
 5. click on 'help'
 
 
 
 5. Setup of your own YAPfront browser
 -------------------------------------
 
 After installing you need to edit some files to make the YAPfront
 browser work with your own databases. 
 
 1. create a 'index.php' or 'myapp.php' for each of your own
 databases/tables; you may copy the 'help.php' of the distribution
 
 2. copy ./setup  to e.g. ./setup.myapp
 
 3. edit in your new 'index.php' the variable $Setupdir and let it
 point to "./setup.myapp"
 
 4. copy ./tmpl to e.g. ./tmpl.myapp and--if you want--edit the
 templates (for a brief description of template tags please check the
 documentation)
 
 5. edit ./setup/setup.inc (see also '9. Special handling of BYTEA
 (BLOB)' below)
 
 6. edit ./setup/customaps.inc
 
 Note: All files in ./class directory should you leave unchanged. You
 may use the same ./class directotry for a arbitrary number of
 databases if you use different 'setup' directories.
 
 
 
 
 
 5. Documentation
 ----------------
 
 Extended documentation is maintained as a PostgreSQL database. The
 name of the database is "yapfront" and the name of the table
 containing the documentation is "help". Usually you will browse the
 documentation using YAPfront itself, but if something failes you may
 browse it with any other tool that knows how to handle a PostgreSQL
 database (like 'psql' or 'pgaccess').
 
 Note: Alpha releases come with very poor documentation. 
 
 
 
 6. Missing features
 -------------------
 
 Pleae check the TODO file for important but still missing features.
 
 
 
 9. Special handling of BYTEA (BLOB)
 -----------------------------------
 
 As of the current version data of type 'bytea' (aka BLOB) are *not*
 displayed or accessible via the data browser. Instead the string
 "Binary Data (BYTEA)" appears in fields of that data type. In future
 versions bytea data will be accessible via links.
 
 The filtering of binary data is done by a hook function. In your
 'setup.inc' you *must* include the following line:
 
   $HookFile = "hook.inc";
 
 Beside of your own hook functions--if you need any--at least the
 following lines *must* appear in the 'hook.inc' file (you may simply
 copy the 'hook.inc' of the ./help/setup directory to your own setup
 directory):
 
   include_once("bytea.inc");
   
   function PostSqlHook($data, $params) {
     $data = filter_bytea( $data, $params );
     return $data;
   }
 
 If you want to write your own PostSqlHook, you *must* call
 filter_bytea() as shown above.
 
 
 
 8. Bugs
 -------
 
 Since this is a alpha release, bugs are likely.
 You should never ever use a alpha release to work with a
 production database.
 
 Please feel free to report bugs or post suggestions. Check
 http://www.ister.org to find the recent e-mail address.