== 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.
2002 - 2007 © Ister.ORG