index

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 = &bull; $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'] = "&bull; 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.