Documentation Index

Html Configuration

Basic Html

The main theme configuration of the site is the directory HTM/ along with the files HTM/HTML.INI and HTM/TEMPLATES.PHP.

The HTML module parses the HTML.INI file into an associative array. This array is accessed by the function html() which is passed the name of the variable to read: html('menu'). If a variable is not set (does not exist) an empty string is returned. If html() 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:

    html('foobar',"foo");

The value can be any PHP type but only strings and integers will make sense.

The TEMPLATES.PHP file is included by the html() function during start-up and that file simply creates the HTML "templates" by 'heredoc's:

$html['open'] = <<<HTML
<!DOCTYPE html>
<html>
<head>
<title>{\$html['title']}</title>
<link href="{\$html['themedir']}default.css" rel="stylesheet" type="text/css">
</head>
<body>
HTML;

That example defines the site's opening HTML template. As can be seen, any other $html variable can be referenced within the $html array (self referencing is undefined).

In the above example title and themedir are set during start-up as the section being viewed and the theme name set by CONFIG.INI (or SECTIONS.INI). See file SECTIONS, see file CONFIG.

Anything placed into the HTML.INI file will end up in the $html array. In addition to the $html array the site's configuration data is in scope in the array $config. Anything placed into CONFIG.INI or SECTIONS.INI end up in $config.

If you look at the code you will see that extra data can be referenced by a template when the data is passed to the display HTML function. For example, the post data is in the array named $record. The template $html['entry'] demonstrates this.

PHP's super globals can also be referenced. If any variable referenced does not exist it will be silently ignored (warnings can be allowed to be issued by the shownotices configuration setting).

The templates must be valid PHP or they will not be displayed and the code silently continues. (There is no configuration setting for these kind of errors but if debugging is enabled, see file DEBUGGING, a diagnostic will be issued.)

Error Messages

This INI file also defines several HTML error messages. Here is our template not found error:

    TEMPLATE = The HTML template <tt>{$html['template']}</tt> not found.

Just like our web templates, any $html data can be referenced.

Comment Error Messages

Messages can occur when submitting comments with bad or missing data. These messages are placed into a special $html variable which is referenced in the comment form HTML template:

    {$html['comment_message']}

Normally, the message is blank (and does not display). If the code detects an error condition it calls a function to set one of the global error messages. For example, if a user comment is submitted without data, the code is similar to:

    if ($data == "")
       
htmlseterror('SUBMIT');

The variable $html['comment_message'] is then set to the message defined in HTM/HTML.INI by SUBMIT and the message gets displayed with the HTML template, the HTML automatically "adapting" (so to speak).

Themes

A theme is a subdirectory of HTM/ and is set by themedir in either CONFIG.INI or SECTIONS.INI.

The default HTML.INI and TEMPLATES.PHP files are always read first so a theme need only override what it needs (and can add anything extra) by creating it's own versions of those two files — see file THEMES.

Although the default theme has a .CSS file such a file is not required for a theme.

Notes
  1. The file is parsed by the PHP function parse_ini_file().
  2. The only real concern here is that array references must be within {}.