About Templates
Html Templates
All "templates" are in one PHP file and are created by use of heredoc
. Not quite as easy as editing .html
files, but the performance increase over multiple files loaded and parsed as the code runs is dramatic.
Unfortunately, if there is a Fatal error: in the template data, that cannot be caught and the code will just exit. However, if debugging is on the last diagnostic message will indicate the template name and the file/function that called it.
A template is straight HTML within which PHP variables can be referenced. This is a snippet of a template:
$html['template'] = <<<HTML
<h1>\$section</h1>
<div style="{\$style['box']}">
The header name and style attributes are PHP data.
</div>
HTML;
There are no code constructs in the templates (there is no template "engine" whatsoever) but there is a "loop support" function to supplement the creation of repetitive HTML (see file HTML.PHP).
Each "template" is named and these names are used in the main display code, DISPLAY.PHP (and in ERROR.PHP). To display the opening HTML there is a function call like:
displayhtml('open');
How the templates are used during a website hit is very simple:
1. The open
HTML template is displayed.
2. For each "post" the entries
HTML template is displayed.
3. The close
HTML template is displayed.
The main menu and navigation menu (sidebar) both have their own templates but are incorporated into the open
template. (Example below.)
When viewing a single post there may be visitor comments and a comment form:
1. The open
HTML template is displayed.
2. The entry
HTML template is displayed for the post.
3. The comment
HTML template is displayed for each comment.
4. The commentadd
HTML template is displayed for the comment form.
5. The close
HTML template is displayed.
There is an HTML data array named $html
that holds all of the templates as well as many more HTML related data, all of which is customizable and extendable. Any HTML template can refer to this data in the $html
array, and even other templates.
Default Html Strings
There is a default HTML configuration file, HTML.INI
, that has several most likely to be changed strings that the templates reference, and any of these can be changed, and any template can be changed to not use them or to use others. Everything placed in the INI file gets placed into the $html
array (which is accessed through the function html()
; see file HTML). Here is an excerpt:
commentstext = comments ($N) commentslink = • $1 addcommentlink = Add Comment
The strings beginning with $
get substituted during runtime; in the above excerpt $N
is replaced with the number of comments a post has, and the $1
is replaced by the value of commentstext
. A result may be:
$html['commentslink'] = "• comments (2)";
Some of these INI strings are referenced by the code only, and change during runtime — the commentslink
value is calculated for each post for example. And some of them are not (meant to be) referenced by templates.
Some $html
values are created only during runtime depending on context. These data, like for menus, are usually referenced just by the templates. Some of these dynamic data are formed with the help of INI values. And all of these can be directly overridden with a template.
The Data Connection
Templates refer directly to $html
data. For example, the open
HTML template is:
<title>{$html['title']}</title> <link href="{$html['htmdir']}default.css" rel="stylesheet" type="text/css"> <div id="header"> <a href="?arg=" title="{$html['title']}">{$html['subtitle']}</a> </div> <div id="main"> <div id="content"> {$html['menu']}
Note that the reference {$html['menu']}
is dynamically created during runtime depending on how the site is configured. It also can be another template if it is defined as a template. There are currently four of these dynamically created "sub-templates".
The post data is in an array named $record
, which is referred to by the entries
HTML template:
<div class="entry"> <span class="title">{$record['title']}</span> <span class="date">{$record['date']}</span> <div class="body"> {$record['body']} </div> </div>
And the close
HTML file is:
</div> </div> <div id="footer"> <span id="copyright">{$html['copyright']}</span> </div>
(If we could make it simpler than that, we would. Well, we can, of course, but that is the beauty of CSS.)
Themes
A theme is nothing than secondary TEMPLATES.PHP
and HTML.INI
files in a subdirectory of the theme's name. If a theme is set — globally or per section — a theme's data simply overrides (replaces) the default theme's data.
The template names and the $record
array are all that is required of a theme. The $html
array is a benefit but need not be used. The open
HTML could very well be:
<title>Welcome to my world!</title> <link href="htm/mytheme/max.css" rel="stylesheet" type="text/css"> <a href="http://myworld.com" title="excellent!">My World!</a> <br>
or whatever one wants. It does not even have to exist. (See file THEMES.)
A Recommended Change
As a tutorial on editing the templates, here is how to remove a section of HTML from the left side navigation menu.
In Admin, click on the (edit) command and then on the link to htm/templates.php. Scroll down or search for the navmenu
template. This is it:
$html['navmenu'] = <<<HTML
<div id="navmenu">
Sections
<ul>
{\$html['navstra']}
</ul>
Other
<ul>
<li><a href="?op=help" target="_blank" title="help files">{\$html[help]}</a></li>
<li><a href="doc/" target="_blank" title="documentation">Documentation</a></li>
<li><a href="doc/source/" target="_blank" title="view source files">Source Viewer</a></li>
</ul>
</div>
HTML;
The reference to $html['navstra']
is the dynamically created section links (as described in the templates file itself).
The "Other" section of the navigation menu will not be needed after set-up and should be deleted and then the templates file be "saved".
Admin Templates
The Admin code has it's own templates and CSS and is implemented in a wholly different manner.
Notes
1. A full list of these strings and their uses is forthcoming.
2. A full list of these values is forthcoming.
3. This is the tricky part (and actually took us a while to get right). Here is a simplified example. The INI string menustr
is like this:
<a class="$selected" href="?arg=$key" title="$subtitle">$name</a>
And the $html['menu']
result is made out of that HTML for each section of the site with the $
designated strings appropriately replaced during runtime. The really nice thing about all this is that a template does not have to reference the menu
data, or a menu
template can be defined and it will be used — basically a template can be anything it wants to be.
4. Again, better documentation is forthcoming.