About Themes
A theme is simply a PHP source file containing HTML (see file TEMPLATES). The default theme is in the directory set by the htmdir
setting in CONFIG.INI
and defaults to htm
.
Creating A Theme
An additional theme is simply a new directory in htmdir
. Creating a directory and assigning the themedir
setting to the new theme directory is the first step to create a theme. Here is an example of how to create a new theme for the "About" section (see file SECTIONS).
In the program base directory, create a theme directory (any name will do except one that exists):
mkdir htm/theme
Add the following line in the SECTIONS.INI
file in the [about]
section:
themedir = theme
Viewing the "About" pages will look no different. This is because the default theme's files are used in the absence of any theme's data. To use new HTML for the theme a new file, HTM/THEME/TEMPLATES.PHP
needs to be created. In this example the open
html will be changed.
Create the template file in the new theme directory with this in it:
<?php
$html['open'] = <<<'HTML'
<!DOCTYPE html>
<html>
<head>
<title>{$html['title']}</title>
<link href="{$html['htmdir']}default.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="header">
New Theme
</div>
<div id="main">
<div id="content">
HTML;
unset($html['quickies']);
?>
When you next view the "About" section you will see the changes.
The "quickies" thing was a late addition to the code as a "Do you think something like this could be done?" kind of thing. It is displayed at the end of the function displayentries()
in the DISPLAY.PHP file. And I mention it to show how to "remove" a hardcoded reference to a template, as that one is conditionally displayed (i.e. it will not be displayed if it does not exist).
In addition, that example demonstrates how the default templates are always read first and then the theme templates are read to override or add to the default $html
array (see file HTML).
In the above example, the open
HTML explicitly refers to the default theme's CSS file:
{$html['htmdir']}default.css
For a theme to use it's own CSS the line would be:
{$html['themedir']}default.css
or it could be:
htm/theme/style.css
whatever.
All hardcoded references to templates are in DISPLAY.PHP, three in ERROR.PHP (which will eventually go away) and four in ADMIN.PHP.
Another aspect of the display code is that if a template does not exist it will not be displayed (and issues no error). So adding this to the theme templates:
unset($html['close']);
will cause the footer to not be displayed. (A debug diagnostic will be issued — see file DEBUGGING.)
More Later
That's just the basics. In time there will be more documentation.
Notes
1. This may change, but only slightly.
2. All configuration variables naming directories automatically get a trailing /
if needed.
3. We try really hard to make this code simple!