#!/bin/false
/****************************************************************************
 * INSTALL :         QUICK ZBASE INSTALLATION GUIDE
 ****************************************************************************
 * $Id: INSTALL,v 1.3 1999/12/17 23:59:56 massiot Exp $
 ****************************************************************************/

Contents :
1. What is ZBase ?
2. Requirements
3. Installation part 1 : set up the DocumentRoot
4. Installation part 2 : create the Business Objects
5. Customizing ZBase
6. Developpement

1. What is ZBase ?
   =============
ZBase is an object framework (set of classes) written in PHP4 allowing to
develop the www frontend of a database very quickly and simply. In ZBase, 
each entry in the database can be considered as an object, and ZBase
provides standard methods to modify or display its content. ZBase is aimed
at experienced web site developers, not at the low-end user. You won't have
this web interface working in less than five minutes.

For the developers, ZBase provides two levels of abstraction. There is a
database abstraction layer, called 'gates', that implements a standard API for
accessing to a database software from ZBase. Currently only PostgreSQL is
supported, but porting it to another SQL-driven database shouldn't be
much of a problem. You can use several of them at the same time, since
ZBase automatically use the adequate gate for each table you request.
As a side effect, you can also have a part of your database on one server,
and an other part on another.

Second, ZBase output is fully customizable on a per-user basis and is managed
through a set of classes that implement an API the objects call. It is
therefore possible to let one user have an interface with bells and
whistles while another has a more sober interface (notion of 'themes'), or
even different languages. Currently only one HTML theme is supported, and
two languages (English and French). You can also have themes whose output
isn't HTML, for scripts or text-based commands, or even XML in the future.

ZBase is organized in modules, several are optional. ZBase provides a class
to authenticate a user and manage logs. Currently we store the crypted
passwords in a special table of the database. ZBase also has a session
module working closely with the database, though it is disabled by default
because of speed issues unresolved so far.

Other modules are available directly through $my_entry->myfunction(), can
be extended by simple method overloading and feature :
 - show module : a set of functions to present the entry in an HTML table ;
 - types module : an API to manage complex types (all databases need types)
                  from within PHP4 ;
 - data protection module : allows you to prevent a user from modifying or even
                            seeing a particular field in a table
                            (optional, not written yet !) ;
 - dependances module : allows you to 'emulate' SQL foreign keys and have
                        a row modify another row in another table
                        (optional, not written yet !) ;

For more information, please see our website at <http://zbase.via.ecp.fr/>.

The current status of ZBase is beta software. Though several optional
modules remain unwritten as yet, what is written seems to be working well,
but has never been tested in a production environment, and the API are not
as documented as we would like them to be (the only documentation available
in most cases is the comments in the source code, which are fortunately
quite detailed). If you do so, please do it at your own risk.

We welcome feedback from the users, including pieces of code or new modules.
ZBase is an open-source project, and we'd be very happy if new contributors
were willing to work with us on it. If you think you can help us, don't
hesitate to drop us a line at <zbase-devel@via.ecp.fr> ! ZBase is distributed
under the GNU Public Licence.

For any help please read this file twice, and then look at the mailing list,
available at <http://zbase.via.ecp.fr/>.


2. Requirements
   ============
ZBase is still experimental and likes to work with friends. These friends
include :
 - PHP 4 (PHP 4b3 is at present the first compatible version, although it
   still has a glitch with the use of booleans, see
   <http://bugs.php.net/version4/bugs.php?id=2781>) ;
 - IMPORTANT : you must enable the track_vars feature of PHP ;
 - PostgreSQL (the version I use is 6.5.3 and it works fine) ;
 - a UNIX machine (ZBase has been written under Linux, and I don't have
   Windows so I can't check, but I think there will be problems with the
   way we store file paths, and the use of symlink. It is NOT impossible,
   but someone has to do the port, and we won't) ;
 - a significant amount of your time (we've done our best to simplify
   the installation process, but every installation is different and
   we won't say you will get it running in five minutes - please remember
   that it is a tool for developers, it doesn't do your job, it just helps
   you do it).


3. Installation part 1 : set up the DocumentRoot
   =============================================
In this part we will suppose that you have a PHP compiled and successfully
installed. First you must create a directory and subdirectories, right next
to the zbase directory you have created by unpacking the archive :
my-base/html (directory that will be accessible from the Web)
my-base/include (classes for PHP)
my-base/log (for the logs)

Then you must modify the configuration of your web server and PHP so that
they take the new directories into account. That means :
 - change the DocumentRoot to /the/path/to/my-base/html (if you use Apache
   it is DocumentRoot in httpd.conf) ;
 - if you want, tell the web server to put its log in my-base/logs ;
 - edit your php.ini file to add /the/path/to/my-base/include to your
   include_path directive, and don't forget to enable the track_vars ;
 - create a new database in PostgreSQL ;

Copy the files zbase/utils/installation/install*.php to my-base/html. 
Take a web browser and go to install1.html. This form will ask you a few 
questions that will be used to generate symbolic links to the zbase 
directories and to modify some files.

Don't forget that the postmaster must be running while you run that script.
If you have any problem with that script... well, read the source, and try
to correct it by hand :-).


4. Installation part 2 : create the Business Objects
   =================================================
ZBase allows you to consider every entry in the database like an object,
with standard methods like search() or modify(), but to do so it needs
some information on the tables you will have, i.e. it needs a new file
containing a new class.

We have setup a script (install3.php, install4.php and install5.php) that
will write the class for you and even send the creation query to the
database. Isn't it nice ? Of course, you can still write the classes
yourself, and that's even the only way you will have access to the most
advanced features of ZBase, but the script is usually adequate for starters.
If you choose the second option, read zb_user_support.inc very
carefully, along with the types_support section in zbase_support.inc,
and good luck :-).

Follow the indications on the screen and create as many tables you need.
If you want the new tables to be searchables, you will have to add them
to config_htmlpage::search_tables in zb_config.inc.

If you want to add data into your tables, you will need a new link in
you index.php page. Follow the example of zb_user to make it.


5. Customizing ZBase
   =================
ZBase is very easily customizable. Of course you can overload many methods,
but that's not the main way. It is a lot easier to modify the attributes
of a field. Read the types_support section in zbase_support.inc for more
details. In a nutshell, the following attributes might be useful :
 - min            Minimum value (for types derived from int, float, date
                  and time only)
 - max            Maximum value (idem)
 - regexp         Regular Expression the field must match

You can also create your own custom types in zbase.inc that would gather
some attributes. Finally, ZBase has been built from the beginning to allow
you to write news gates, new themes, and new access control modules. For
indications on them, please see the already existing files, there are
a lot of comments.

This section is quite short and will naturally be improved in the future.


6. Development
   ===========
ZBase has been written mostly by Mathieu Poumeyrol (gates, types),
<mathieu.poumeyrol@via.ecp.fr>, and Christophe Massiot (services, show, zbase,
html pages), <christophe.massiot@via.ecp.fr>. Icons and stylesheet are by 
Pierre Baillet, <pierre.baillet@via.ecp.fr>.

We welcome other developers to work with us on future versions. We have a
development mailing-list <zbase-devel@via.ecp.fr>, and we can give
write access to the CVS to contributors. Please send us a mail if you
want to help.

-- 
CM (1999/11/25)
