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.
A template is straight HTML within which PHP variables can be referenced. This is a snippet of a template:
$html['template'] = <<<HTML
<h1>{\$config['section']}</h1>
<div style="{\$html['boxstyle']}">
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.
Each template is named and these names are used in the main display code, MOD/DISPLAY.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
template is displayed.
2. The entries
template is displayed for each post.
3. The close
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 the output is simply:
1. The open
template is displayed.
2. The entry
template is displayed for the post.
3. The close
template is displayed.
When viewing a single post there may be comments and a comment form:
1. The open
template is displayed.
2. The entry
template is displayed for the post.
3. The comment
template is displayed for each comment.
4. The commentadd
template is displayed for the comment form.
5. The close
template is displayed.
There is an HTML data array named $html
that holds all of the templates as well as many HTML related strings, all of which are customizable and extendable. Any 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
(and the configuration data, $config
; see file CONFIG). For example, the open
template is:
<!DOCTYPE html> <html> <head> <title>{$html['title']}</title> <link href="{$html['htmdir']}default.css" rel="stylesheet" type="text/css"> </head> <body> <div id="header"> <a href="{$config['siteurl']}" title="{$html['title']}">{$html['subtitle']}</a> </div> <div id="main"> <div id="content"> {$html['menu']}
Note that $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
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> </body> </html>
(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:
<!DOCTYPE html> <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. Missing or empty templates are silently ignored. (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="{\$html['helpurl']}" target="_blank" title="help files">{\$html[help]}</a></li>
<li><a href="doc/" target="_blank" title="documentation">Documentation</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".
A LOCALHOST installation would be highly recommended to test all your changes.
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.