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.
- The file is parsed by the PHP function
parse_ini_file()
. - The only real concern here is that array references must be within
{}
.