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') for example. 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 frowned upon).

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.)

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 {}.