/ 
Labyrinth-Demo-1.04
River stage zero No dependents
/ Labyrinth::Demo

NAME

Labyrinth::Demo - Labyrinth Website Management Framework - Demo Website

DESCRIPTION

Documentation overview for the Demo Website of the Labyrinth Website Management Framework.

Labyrinth began life in 2002, with a small set of plugins to enable various features of web site management.

This demo website uses the core set of plugins to provide an example of a website management system.

These plugins provide the functionality to manipulate core aspects of the data used within Labyrinth. Several of these plugins only provide administration features.

ADDITIONAL FILES

In order for your website to work with Labyrinth, some additional files are required. This package provides the standard set of files to enable Labyrinth and the Core plugins to work with a blank canvas. These files consist of SQL, template and configuration files, together with some basic CSS and Javascript files.

Install these into the website structure and edit as necessary to implement the layout and functionality you require for your purposes.

Please note that included with this distribution are files designed and developed by other people. Notable are the following:

PixelGreen

Version 1.2

CSS Layout and Design by Erwin Aligam, release under the Creative Commons Attribution 2.5 License - http://creativecommons.org/licenses/by/2.5/

See http://www.styleshout.com/ for more details.

TinyMCE

Version 3.211

A Javascript WYSIWYG Content Editor by Moxiecode Systems AB, released under the GNU Leseer General Public License (LGPL) - http://tinymce.moxiecode.com/js/tinymce/jscripts/tiny_mce/license.txt

See http://tinymce.moxiecode.com/ for more details.

INSTALLATION

To set up the Demo Website, install via a CPAN client (such as CPAN.pm, CPANPLUS or cpanminus) to ensure you install required prerequisites. Then copy the directory contents under the 'vhost' directory into your web server directory. For this example the path to these files and directories is assumed to be '/var/www/demo'. If you wish to change this, please update the file paths used in 'cgi-bin/pages.cgi' and 'cgi-bin/config/settings.ini'

If you use Apache, include the configuration snippet contained in the file 'vhosts.conf', in the appropriate Apache configuration file. Directions for other web servers will be included at a later date.

Create a MySQL database called 'demo' and use the base file 'cgi-bin/db/demo-base.sql' as a starting point. If you wish to specify a fixed user to access the database, you may wish to review the 'grant.sql' file or amend the 'settings.ini' as appropriate.

You should now be able to start your Apache instance. Update your hosts file as necessary to point to your new virtual host.

A more complete installation and configuration script is planned for the future, which can also install plugins.

LABYRINTH DIRECTORY STRUCTURE

./cgi-bin
    /config		- contains top level configuration files
       /requests	- contains despatch tables
    /db			- database dumps
    /lib
       /Labyrinth	- Labyrinth Core modules
          /Plugin	- Labyrinth Plugin modules
    /templates		- Template Toolkit templates
./html
    /cache		- cache where reports are produced
    /css		- website CSS files
    /images		- website image files
    /js			- website JavaScript files
       /tiny_mce	- Tiny MCE JavaScript application files
./toolkit

As mentioned included in the package is the vhost entry from an Apache configuration file. This file contains the rewrite rules that translate user friendly URLs to the local CGI call. However, it is not necessary to have rewrite rules, in the event you are unable to use them, and the application can quite happily function with full 'cgi-bin/' type paths.

The './cgi-bin/pages.cgi' file is the core startup script, that simply passes the settings file, and initiates Labyrinth. The 'act' CGI parameter contains the primary action required. Throughout the duration of a request, the current action may change several times, with each referencing the despatch tables to load and run the correct functions and render the correct templates. Each user has a nominated "realm", which is the section of the site they are given access to. The realm despatch table is used to load and run and default functions, and can thus be used to render different skins and/or layout templates.

The CGI parameters are validated against the './cgi-bin/config/parserules.ini' file. The rules are built from these entries and passed to Data::FormValidator. Each entry's fields refer to parameter name, whether mandatory, default value, preprocessing function, constraint function and finally the regular expression. If a constraint is provided the regular expression is ignored. Where the parameter name looks like ':^LISTED', this is a regular expression match against the parameter name (where the ':' character is removed). This enables parameters which have a changeable suffix, can apply the same constraint or regular expression against each matching parameter's value.

All SQL statements are called using a Phrasebook Design Pattern. As such the './cgi-bin/config/phrasebook.ini' file contains all each phrase and associated SQL as used within the application. To aid readability SQL can be split onto multiple lines, using the '\' character as the last entry on a line to continue onto the next.

Templates are built from the given layout, see the appropriate realm entry in the despatch table, incorporating other templates as required, including the 'content' template as specified by the last action command. See the appropriate despatch table to reference the appropriate content template.

Tiny MCE is used by Labyrinth where appropriate for text area input. However, this is only activated on the pages where it is appropriate.

The set of scripts within the toolkit directory typically provide ad-hoc or timed (e.g. via cron) functionality. The scripts are not intended to be run via the web server, but often provide support functionality, such as creating static pages or running periodic cleanup tasks.

DEMO WEBSITE

To see a working example of this distribution, please see the following link:

http://demo.missbarbell.co.uk

ADDITION INFORMATION

Although Labyrinth has long been in development, documentation has not been a priority. As such much of the documentation you may need to understand how to use Labyrinth is the code itself. If you have the inclination, documentation patches would be very gratefully received.

The Labyrinth website [1] will eventually feature a documentation site, wiki and other features which are intended to provide you with the information to use and extend Labyrinth as you wish.

[1] http://labyrinth.missbarbell.co.uk

SEE ALSO

Labyrinth, Labyrinth-Plugin-Core

http://labyrinth.missbarbell.co.uk

AUTHOR

Barbie, <barbie@missbarbell.co.uk> for Miss Barbell Productions, http://www.missbarbell.co.uk/

COPYRIGHT & LICENSE

Copyright (C) 2002-2014 Barbie for Miss Barbell Productions
All Rights Reserved.

This distribution is free software; you can redistribute it and/or
modify it under the Artistic License 2.0.