Documentation Index

Site Configuration

Basic Config

The main configuration of the site is the file CONFIG.INI. Here is an excerpt:

    sitetitle = This is the Cool Website
    copyright = "© 2013 Cool Inc."
    debug = 0
    postlimit = 10000

Since the PHP parse_ini_file() function is used to parse the file some values may need to be delimited by quotation marks.

The CONFIG module parses this file into an associative array (see file MOD/CONFIG.PHP). This array is accessed by the function config() which is passed the name of the variable to read: config('themedir'). If a variable is not set (does not exist) an empty string is returned. If config() is called with no arguments the entire array is returned.

During runtime a variable can be set by passing a value in the function call:

    config('foobar',"foo");

The value can be any PHP type.

During runtime some settings are set according to the site section being viewed (see file SECTIONS). For example, viewing the base site:

    setting         value
    section         "root"
    pagedir         "pages/root/"
    importdir       "import/root/"

Viewing the section "about" (?about) they are:

    setting         value
    section         "about"
    pagedir         "pages/about/"
    importdir       "import/about/"

The CONFIG.INI file is heavily commented.

Directory Names

There are several directories that the code expects to exist which are named in CONFIG.INI. They all end in dir. They need to exist (and do in the archive of course). (Some of them need to be writeable for full functionality.)

The names do not need a trailing / but can have one (the code checks for it, adding one if needed).

Three of the directory names are aliased by functions:

    function	alias
    htmdir()	config('htmdir')
    imgdir()	config('imgdir')
    themedir()	config('themedir')

Sensitive Data

No sensitive data is stored in the configuration array.

Modifying The Code

For anyone interested in modifying the code, this section explains how to use a new configuration setting. Anything placed into CONFIG.INI will end up in the configuration array.

Say you are looking at a block of code and want to change it so that it becomes conditional. All you have to do is put the block within a "config test".

Say there is this, and you don't particularly like it:

    print "Fooby Looby!";

To conditionalize it, step one is to add the config test to the code:

    if (!config('nofoobylooby')) {
    	print "Fooby Looby!";
    }

And then add the setting in CONFIG.INI:

    nofoobylooby = 1

That is all.

Because config() returns "" (empty string) if a config variable is not defined, we chose to use an example with a double negative on purpose — this way the default operation remains the same if you (or someone else) do not define the new setting in the ini file. (You obviously do not have to do things that way if you do not want to.)

Also, let's say you are looking at the code and see something like:

    $test preg_match("/[a-zA-Z0-9]/",$name);

and see that it is used twice in the same block! And you go, "Ya know, it'd be way cool to fix that!"

To do so, step one is to make the code something like:

    $namematch config('namematch');
   
$test preg_match($namematch,$name);

and the new INI setting is:

    namematch = "/[a-zA-Z0-9]/"

The example is trivial, but when much of the application is configured this way it becomes, well, trivial to configure and to make changes.

Caveats

The root section's configuration values are common to all sections (unless overridden by a section value; see file SECTIONS). This means that if the root section was wanted to be the only section with a unique value, say reversesort = 1, all other defined sections must explicitly have reversesort = 0.

Most settings are not defaulted, which means there will be errors if some settings are not defined.

Disallowed section names (currently root, users and visitors) are not checked and will causes errors if defined.

For a real application the latter two would be a real problem — in that an Admin edit with a single misspelling could possibly break the code, with the potential of preventing Admin from fixing the error (requiring an external configuration edit to fix it). Although I can live with that other people may not want to. There are solutions which will eventually be put into place.