What is a template?

A template is the basic HTML shell that each page uses. Notice the uniformity through this site (and most others), this wasn't done by chance and it was probably not done manually. While you can copy and paste the common bits into each file, this is time consuming and prone to errors, and extremely difficult to modify in place.

The solution is to separate the stuff that is common to every page into a separate file and dynamically combine them when the page is requested. This reduces data redundancy and makes changes to the site design quite a bit more manageable.

waf templates are html files, which may contain executable PHP code. Within the HTML file are HTML comments which are substituted for page content at request time. The following tags are implemented.

<!-- TITLE -->
Replaced with the contents of $Page['title'].
<!-- SUBTITLE -->
Replaced with the contents of $Page['subtitle'].
<!-- HEADERS -->
Replaced with the contents of $Page['headers']. Intended use is for additional content within the <head> tag, so the template should place this in that section.
<!-- BODY -->
Replaced with the contents of $Page['body'].
<!-- NAV -->
Replaced with a string built from each item in the array $Page['nav']. This is explained in more detail below.

The comment tags are replaced within the template each time they occur. The only tags likely to be useful more than once are TITLE and SUBTITLE though.

Headers

The $Page['headers'] array is a convenient way to organize additional HTML headers such that they can be easily removed or changed throughout the execution of a page. At the top of a page you may set three headers that are used in various combinations through the rest of the page, then selectively unset() the items that aren't required later on. The majority of the time you shouldn't even need to use the headers array, though. Most of them should be specified statically in the template.

The array is enumerated at request time with each value simply being concatenated to the last, and the resultant string is inserted.

Navigation Bar

The navigation bar is built as an associative array of caption/URL tuples. When the template is being expanded this array is enumerated and each item is added to the navigation string in the order in which they appear in the array. The framework attempts to call the function waf_NavCat($String, $Caption, $URL) to append each item. This function doesn't exist by default, but it can be created as part of the template, in order to specify how each item should be added. The function takes in the current string and returns the modified version each and every time it's called (once for each navigation item). If the function doesn't exist then each item is added as a link with a vertical bar (|) between them.

Example 1: Bare template with horizontal navigation bar

<html> <head> <title><!-- TITLE --> :: <!-- SUBTITLE --></title> <!-- HEADERS --> <style> BODY { background: #FFFFFF; color: #000000; margin: 0px; } #PageHead { font-size: 22pt; padding: 3px; } #PageTitle { display: inline; } #PageSubTitle { display: inline; font-size: 16pt; font-style: italic; margin-left: 1em; } #PageNav { border-top: 1px solid black; border-bottom: 1px solid black; padding: 1px; font-size: 10pt; background: #F0F0F0; } #PageNav A { text-decoration: none; padding-left: 0.5em; padding-right: 0.5em; } #PageBody { margin: 1em; font-size: 12pt; } </style> </head> <body> <div id='PageHead'> <div id='PageTitle'><!-- TITLE --></div> <div id='PageSubTitle'><!-- SUBTITLE --></div> </div> <div id='PageNav'><!-- NAVIGATION -->&nbsp;</div> <div id='PageBody'> <!-- BODY --> </div> </body> </html> <?php function waf_NavCat($NavStr, $NavItem, $NavItemURL) { if($NavItemURL == '') return (empty($NavStr) ? '' : $NavStr . ' | ') . $NavItem; else return (empty($NavStr) ? '' : $NavStr . ' | ') . '<a href="$NavItemURL">$NavItem</a>"; } ?>

The layout of the HTML here is pretty basic, and you can see where the substitution points are. This template is very closely based on the one used for this site, in fact. Notice the waf_NavCat() function, the basic functionality of the navigation array has been extended, such that non-links can be added by specifying a blank URL in the tuple. This is obviously a very basic example, but it demonstrates much of the functionality available in the template file.


Template Overriding

Within a page you can specify an alternate template to use by setting $Page['template-name'] to the filename of the template. If the alternate template can't be loaded for any reason then the framework will fall back to the site's default template.

This is useful in combination with the .common.php feature to provide a hierarchical structure. For instance, this site is run as a sub-directory of my personal site, they share the same waf instance; but notice how the formatting is totally different. This was a matter of adding a line to .common.php:

$Page['template-name'] = WAF_PAGES . '/projects/template.projects.html';

.common.php is not inherited, so it must be replicated into each subdirectory for which you wish to override the site-wide defaults. This may change in the future, as inheritance here would make sense.

This page last updated: Mon Feb 25 22:04:22 2013 (GMT)