LayManSys Setup Guide

Some LayManSys modules need to have some constants set to find other configuration files, such as the global etc/laymansys.rdf:

The global etc/laymansys.rdf is a normal RDF file as described by the LayManSys Elements and Namespace reference. An example file is distributed with the LayManSys library package resp. available in the CVS repository. The more you can fill meta information into this file, the less do you need to specify later in your documents RDF file.

The really important configuration setting here is the array returned by LayManSysDefaultHeaderOptions. Each configuration setting is a string and so may contain any character you like with one exception: Keys having a dot as first and last character are "private" LayManSys settings. There are currently the following keys you can use customizing LayManSys:

All of these settings can be overwritten on a per file base using an optional array as second argument to LayManSysHeader; see LayManSysHeader call for an example.

This file is the central error handler for LayManSys; it contains the two error callbacks handle1stStageError for errors while generating the header and handle2ndStageError for later errors. Both callbacks make use of the logError function from the module errors/log.php. By including a different module you can use your own logError function.

handle1stStageError shows the HTTP 500 error document and than exits by default. Logging the error is done implicitly by errors/500.php. You may change this behaviour by using another error document or continuing the script execution; simply delete the exit statement for this.

The function handle2ndStageError itself is "optional" because you can overwrite this callback in the laymansys/config.php. It logs the error and displays a error message by default. You may want to change this message because the default string is in German (this comes from the fact that I first used LayManSys only for my private homepage).

LayManSys contains a module for writing a default footer element and closing the html tag. The function writeFooter, that you can modify regarding your needs, writes the documents copyright notice inside a address id="footer" block and closes the body and html tags. It should be the last function executed before ending the script. The function prototype may be interesting for you when modifying this file:

$endTags contains tags that need to be closed at the documents end. The purpose of $xml is to indicate whether the output should be HTML or XHTML. But the default footer does not need this information.

The LayManSys distribution contains an example error page for HTTP 500 errors that is called by error.php. This default file contains PHP code for logging the error information to a database, using the module errors/log.php and displaying a nice HTTP 500 message to the user. You can customize this file as you like for your own needs, you are even allowed using it as ErrorDocument for your webserver.

The distributed file errors/log.php contains the function logError for logging error messages to a SQL database. For this, you have to define some constants so that the logError function can connect to the SQL server:

You have to modify this file if you are using a database management system other than MySQL, that means, replacing all direct MySQL API calls, but this are only a few.

If you would like to use LayManSys' default error handling and logging mechanism, you have to set up a SQL database for the error log. The directory lib/errors/ contains the SQL file error_log.sql that you can use for creating the necessary error_log database table. Although exported from MySQL, you should be able using the file with other database engines without larger modifications.

The most simple way using LayManSys is by including one of the LayManSys wrappers in the laymansys/auto/ directory:

<?php
include_once('my_error_handler.php');
include_once('/path/to/laymansys/auto/html4.php');

// $meta contains the LayManSys meta information
?>
<!-- Start here your HTML body right now! -->

The given filename my_error_handler.php is used here as a place-holder for your error handling module.

Each of the following auto-headers includes the LayManSys main file, lib/laymansys.php and calls the LayManSysHeader using a certain HTML document type.

If you want to go the real lazy-mans way, you can use the auto-headers whose name ends with -default.php. They include the lib/laymansys-default.php library file which provides a complete error-handling and -logging mechanism. Their names are comparable to the ones above, e.g. html4-default.php is the all-inclusive version of html4.php and their usage is the same.

If you want to use LayManSys in a document where you need to set some config.php options, you have to include the laymansys.php directly and call LayManSysHeader explicitly. The function takes as first parameter the HTML document type, something like HTML 4.01 or XHTML 1.0 Strict. The second parameter is an optional array of config.php settings. The third parameter is also optional and can be used for passing $meta from other sources than RDF files, e.g. from a database. An example of a LayManSysHeader call looks like this:

<?php
include_once('my_error_handler.php');
include_once('/path/to/laymansys.php');

$meta = LayManSysHeader('HTML 4.01', ,
		array('my.rdf' => $category),         /* options */,
		array('accessRights' => 'public'),    /* meta data */);
?>
<!-- Now we are in the HTML body. -->