AXYL OVERVIEW
=============

1. Synopsis
-----------
This package constitutes a ready-made methodology for the implementation of a
database-backed website, using Php as the programming language. It requires
a minimal database schema (usually implemented in PostgreSQL but may be in any
database flavour supported by Php) which caters for a fairly standard way of
maintaining users, user-groups and sessions. This is detailed below.

[NB: There is provision for running Axyl without any database backing, for those
people wanting to provide a simple site without much in the way of dynamic
content. This is done with a simple flick of the wrist using the Control Panel
supplied as control-panel.php in AXYL_HOME/lib.]

[NB: Phpdoc documentation detailing the classes of the 'engine room' of Axyl
(the modules in the AXYL_HOME/lib sub-directory) can be found in a separate
Debian package axyl-doc]

[NB: Install the Axyl documentation package, create a 'demo' website and take
the Axyl Tour to discover how to make the most of Axyl development in detail.]


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2. Database Schema

[NB: although Axyl is database-independent and no dependency is enforced, the
development has been done using Postgresql, and this is therefore recommended
as the database of choice, and is used frequently throughout this document.]

The schema for the basic Axyl core is to be found in 'db/postgres/axyl_core.sql',
with a few additional triggers in 'db/postgres/axyl_trig.sql'. If you have
Sybase Powerdesigner, there is also a Data Model in 'db/postgres' called
'axyl_core.pdm'. For those wanting to simply look at the schema, there is also
a PDF in the 'db' directory called 'axyl_core.pdf' which can be viewed or
printed as required.

Note that for a functional Axyl website you will also need to insert some core
data, which can be found as SQL in 'db/postgres/axyl_core.dat'.

The schema content is just the basic minimum to implement Axyl's core
functionality, and the idea is that you will take this platform and add on your
own tables and fields as required. All Axyl table-names are prefixed with 'ax_'
to prevent namespace issues, however feel free to customise these tables as
well. As long as the customisation doesn't remove schema which Axyl requires,
this is fine. Typically, for example, you might want to add fields to the
ax_user or ax_wwwsession tables.

2.1 Creating a new Axyl website
Out of the box, Axyl provides you with a script to create a brand new website,
database (Postgres only at this stage), and Lucene domain. This is to be found
in:
  install/create-axyl-website.sh

Just run this script (as 'root') and answer the questions.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3. Configuration

Axyl has a Control Panel page which is to be found in the 'lib' directory.
The recommended option is to copy this script from the 'lib' directory up
into your website root directory, and then view it in a browser at:
  http://<your website url>/control-panel.php

You will also have to make 'application.xml' writeable to the web-server.

That way, any future Axyl library enhancements to control-panel.php will be
available via update the same as with the other library modules.

IMPORTANT NOTE: do NOT do the above on a live/production website, since
making configuration files like 'application.xml' is not a good idea.
Instead, do all your configuration changes on a development site, behind
a firewall, and then update a read-only version of 'application.xml', and
remove 'control-panel.php' from your live site library code. To make sure
your website permissions are set correctly, you can run the following
script:
  install/setperms.sh

The Control Panel is basically a large form with all the Axyl options
configurable and able to be saved. The resulting configuration is put into
"application.xml" in the root website directory. Always use control-panel.php
to change this file, rather than editing directly.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4. Database support

Axyl has a nicely separated database-independent layer so that it is pretty
straightforward to add any flavour of database which Php supports. Currently
Postgresql is the only one which is extensively tested and supported by the
installation scripts etc. however modules exist for ODBC, MS-SQL Server,
MySQL, and Oracle. Of these MySQL is fairly well tested, and Oracle is currently
going through that process. Getting the others to work should be fairly simple.

To provide additional database modules, have a look in the library directory
(AXYL_HOME/lib) for modules named "db-*.php". For example, "db-postgres.php"
contains the low-level access routines for Postgresql. After writing another
one of these, just include it in the relevant place in "database-defs.php".

You can connect to any number of databases quite easily with Axyl. Use the
Control Panel to configure these (see above). You can then select a given
database by using the "database_select()" method of the global $RESPONSE
object. For example, if you connected to two databases, the default (listed
at the top in the Control Panel) one being named "mydb" and a second one
called "orac", then Axyl would initially be running any queries you executed
against "mydb". To run some against "orac" you would":

    $RESPONSE->select_database("orac");
      <various queries..>
    $RESPONSE->select_database();

The call with empty parameters selects the default DB (in this case "mydb").


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
5. Axyl Directory Structure

NOTE: This documents the directory structure of the Axyl installation, not a
website that you might create with it.

    compat          - Scripts compatible with non-Postgres databases
    db              - Database-specific documents and schema
    doc             - A few bits and pieces of documentation
    install         - The Axyl install scripts
    lib             - The Axyl library. All the Axyl classes.
    lib/img         - The Axyl library images symlink (buttons mainly)
    lib/js          - The Axyl library javascript modules symlink
    scripts         - Update and example scripts
    www             - The default Axyl website hierarchy:
    www/templates   - Holds templates for default and additional themes
    www/img         - Default images directory for the website
    www/inc         - Included fragments of Php code
    www/var         - Area of website writeable to webserver:
    www/var/cache   - Cached copies of webpages stored here, if any
    www/var/catalog - Area for user-uploaded media/documents
    www/var/cm      - All user-created content-managed pages


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6. The Templates Directory

The "templates" directory contains some templates to serve as examples and to
implement the prototype website out of the box.

The website generation process recognises that a site generally has a handful
of "page types".  For example you might have a "main page format",  and a
"popup page format" (as in this case). The main page format would cater for
most of the pages of the site, and the popups could provide a page free of the
menus and ad-banners etc, for collecting input from a user.

You can, however, have as many page types as you want. Having decided on the
number, give them names such as "main", "popup", "boris" or whatever. Then
create a template for each one in the "templates" directory, named
"template_???.html" where you replace the "???" with your page type name.

Next, have a look in "site-webpage.php". This codefile is a key file for
generating every single webpage on your site. It contains some important
routines for generating content, in the one place. For example there's a
section for generating the header, and the side menus. Right at the bottom,
this stuff is actually called in a short section which does things according
to the template being used for the page. However it's important to note that
the role of "site-webpage.php" and what it contains is ENTIRELY up to you.
It is just a common file which can be included in all your pages to do common
stuff. You put what you like in there. Of course you could also completely
empty it, or alter your code so that it is never included - up to you.

When you create a brand new page, you just do a few simple things. First of
all you will include "application.php". More on this important module later.
For now just know that "application.php" contains the configuration info,
such as the database connection details etc.

Secondly you will make a call to the "page()" method of the $RESPONSE object
like this:

  $RESPONSE->page("My Page");

This tells the global $RESPONSE object the specifics of the page you expect
it to return to the browser requesting it. In this example we just tell it
the title of the page "My Page". A more complex example would be:

  $RESPONSE->page("My Page", "popup", "myothertheme");

This tells the $RESPONSE object that the title of the page is "My Page", the
template to use is "template_popup.html", and the theme to apply is
"myothertheme".

In the case of the theme being specified, the $RESPONSE will go and look in
./templates/myothertheme for the stylesheet, templates, and images.

Finally, you will include the "site-webpage.php" module, which contains your
customised versions of the header, footer and side-menu functions and is
responsible for populating these with the default content.

NOTE: Axyl supports the production of WML (Wap Phone) content as well. A
typical WML page would use the "card()" method instead of "page()", to
create a default object called $CARD. A typical WML page structure would
be as follows:

 // Initialise card
 include_once("application.php");
 $RESPONSE->card("My WAP Page");
 // Create content
 $CARD->insert_paragraph("Hello World!");
 // Send response to WAP phone
 $RESPONSE->plugin("MAIN_CONTENT", $CARD->render());
 $RESPONSE->send();


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
7. Page creation via Axyl

Page creation can also be done by browsing to "axyl-sitepages.php" which
comes with Axyl. Click the Add button and enter title and path. Next
decided whether you want a Content-Managed page or a page you will be
coding up by hand. For content managed pages, make sure "Managed" is
checked. When you save this, the system will copy the relevant template
page and set the title etc. to what you specified. It's a quick way of
generating new pages for the site.

Another method of creating Content-Managed pages is via the Menu Builder.
This is accessed via the MAINT option on the Axyl menu (you have to be
logged in as a user with Admin group membership). At the bottom of the
menu setup form is a place where you can create new pages which are to
contain content-managed layouts.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
8. context-defs.php

This code file contains an object which is instantiated by the session
(ie. every time a user accesses a webpage) and makes available various context
variables that you need to make accessible from page to page.

Naturally enough these are heavily dependent on your application, so have a
close look at this file, and customise it as required. As it stands, it
does absolutely nothing, since the database statements to acquire and
save context data are entirely specific to what you want to do.

The approach is generic, in that it provides a single place where you can
collect the required context information, in whatever way you think best.
Usually this will be by using the database of course, but the tables and
fields you use for that are up to you.

So, in general proceed as follws:
Decide what you want to keep as session context values. For example, on the
Rugbylive site, we keep the "game_id" of the current game which is being
looked at as a context variable. On a commercial site you might like to keep
a list of products in a shopping basket etc.

Find some way of storing these things permanently, against the session of the
user. The usual way is to create additional fields on the "wwwsession" table,
but you could create another table or tables to do this.

Write code in the "getvars()" and "putvars()" member functions to access the
data fields you have provided.

Optionally, decide whether to grab all or some of this data when you instantiate
the context object with a "new" call, by customising the constructor function.

For example, you might want to automatically always do a getconfig() in this
constructor, or maybe not, depending on your requirements.

In your application, the context is automatically made available to you by the
system in a global object called "$CONTEXT". This is done in "application.php",
which is included every time by "site-webpage.php", so there is nothing else
you need to do except use it (ie. you don't need to call "getvars()"). This is
shown here..

// To access an individual context value..
$foo = $CONTEXT->myval2;

// To access the system configuration
$foo = $CONTEXT->configvalue("rootdir");

// To assign a new context value..
$CONTEXT->myval2 = $foo;

// To save all context values for next time..
$CONTEXT->putvars();

The above examples cover just about everything you need to do with context
values: accessing them, modifying them, and saving them.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
9. Themes

Axyl supports themes. Quite often you have a bunch of dynamic content and you
want to display this same content on pages with different "looks". For example
you might have a database table to display to two different clients, on pages
which are branded according to the companies they work for. In one case the
pages have a bright yellow logo splashed across the top and the menu in the
footer, and in the other, the logo is completely different, and the menu is
down the left side.

How nice it would be if you could just write the page once!

Well, with Axyl you can. The procedure would be to develop the two templates
according to the layout described above, using the relevant images etc. for
each theme, and putting the dynamic content into the HTML at the correct
place identified by some unique name inside an HTML comment tag like:
    <!--MY_DB_TABLE_DATA-->

Say the companies were "acme" and "microsnot". You would create two theme
directories in the "templates" directory:
    templates/acme
    templates/miscrosnot

Each would hold the appropriate template "template_main.html" for the
look of the site. You would also probably put customised stylesheets into
the directories too, each called "sitestyle.css" but obviously containing
the styles appropriate to the look for each theme.

Images would be put in a subdirectory of each theme. If, in your top
directory (ie. the default theme) you were using an images directory
called "img", then you would place your theme images into:
    templates/acme/img
    templates/miscrosnot/img

After that the system will do the rest. You simply call the website pages
with a theme on the URL, for example:
   http://www.mywebsite.com/index.php?theme=acme

And the page will be rendered using the templates, images, and stylesheet
for the acme "look".

Instead of specifying it on the URL you can customise your site-webpage.php
module at the bottom. You could check the user ID of the logged in user
and set the theme accordingly, or maybe an IP range. Whatever.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
10. Cacheing

Axyl supports cacheing for pages which might come in for a hammering on a
busy site. To enable this on a given page just put the following call in
near the top:
    $RESPONSE->cache(3600);

The parameter in the brackets is the number of seconds to cache for before
regeneration occurs. Tune this according to your site. Obviously if you
are expecting the dynamic page content to change every minute, then choose
a figure like 30-60 seconds.

This is a useful mechanism for pages which have a fair degree of database
activity to generate and which might get flooded with hits. The cache
duration will ensure that the database server gets a respite, even if you
only cache the page for 15-30 seconds or so.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
11. Axyl LuceneServer

Axyl can have an additional package bolted-on, called axyl-lucene. See the
README in that package for further details.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
12. Further Documentation

There are one or two other sources of documentation in the Axyl distribution
and these are found in the separate axyl-doc package or tarball. Install
this package for access to that documentation. Further details of the content
of this package are given below.

The Axyl documentation effort is, for the most part, concentrated around
the API Reference since this is what is of the most use to a prospective
Axyl developer.

This documentation comes in the form of a self-consistent set of web
pages, prodiced by PhpDocumentor (http://phpdoc.org) an excellent
system based on the Javadoc documentation methodology.

The API documentation can therefore be accessed by pointing a browser
to the 'api' sub-directory of /usr/share/doc/axyl-doc.

Aside from the API documentation there is also a short introduction for
users of the Axyl content management system in PDF format, and a text
file containing some tips on developing applications which use the
Lucene search engine in to following files:
 axyl_cm_userguide.pdf
 lucene-dev-HOWTO

Axyl Demo
=========
The second part of the documentation is provided by an example Axyl
website. This website is installed with the very same schema that the
'empty' one that you get when starting a new Axyl development, but also
populated with data, in the form of an Axyl Tour tutorial.

The Tour gives you a complete rundown on how Axyl hangs together and how
to develop your own applications with it.

To install an Axyl demo website, just navigate to the axyl documentation
directory, and into the 'examples' sub-directory. Execute the script
called 'create-axyl-demo.sh' and this should result in the demo website
being built for you. Point your browser at the resulting homepage and you
should be able to take the Axyl Tour.


# END
