1. Introduction

a. Overview

Templation is an extremely lightweight web framework oriented towards content-driven sites. The core idea is to allow elements to cascade down through the directory structure, so that repeated elements only need exist in one place and can be customized easily in specific instances. The ultimate goal is that each file in your document root only contain the content for that single page; the global elements will all be specified by a template and implicitly built according to where the requested page exists within the hierarchy.

Project Goals

1. Eliminate redundancy of page elements by hooking into the natural hierarchy of a standard website.
2. Work primarily with standard HTML/XHTML so it is easy to learn and work with in any HTML editor.
3. Stay out of the way of existing code and stay as compatible as possible with other PHP applications.
4. Provide facilities to perform arbitrary transformations of web pages.
5. Cache and export all of the above functionality so it can be used either live or as a development tool.
6. Easy to install and configure so that it can easily be added incrementally to any site.

b. Terminology

Templation defines a whole new method of website construction and thus requires a slew of specific terms to be used in the documentation. Please be familiar with the following definitions:

Settings / Configuration

The Templation configuration is controlled by the Templation class variables which are initialized to standard values that can be modified in the settings.php file.

Data repository

This is the directory containing templates, widgets, actions, top-level includes, and settings. By default this will be a directory named data relative to the Templation class file, but it's often handy to move it to a more accessible location.

Source file(s)

The source file refers to the actual page requested from the web server which should ideally contain only the content specific to that page. When used in plural, source files may refer to any file being read in for content such as include files. Source file specifically does not refer to files that operate as part of Templation, this includes the Templation class, and any widgets or actions.

Widget

A widget is a piece of PHP code that is called by a template to generate some output. This differs from other PHP in your source files because it is executed with Templation and its output will be cached, which means there are special implications for writing proper widgets.

Action

Actions are similar to widgets, except they are specified in meta tags rather than in templates and they run after the page is completely built, so they are able to perform transformations of complete documents.

Hierarchy

The Templation hierarchy is the series of file system directories between the source file and the website root directory, with a top-level available in the data repository for server-wide data. The main purpose of Templation is to provide hooks to control the output of your pages at any of these levels or even across multiple sites. Templation hierarchy information is stored in special subdirectories in order to keep it separate from standard files.

Include

One of Templation's core functions is to specify a filename that will be recursively located in the hierarchy. This means that a template can specify an include file by name, but that file may vary by the source file location. Widgets also an API that allows direct access to includes from the hierarchy.

Meta data

Meta data is the information gathered from the hierarchy that applies to a given page. This data takes the form of key/value pairs specified by standard HTML meta tags in the source file and throughout the hierarchy. The term 'meta data' is a bit of a misnomer because meta data is often used as literal content. However, it is also used to control Templation itself (eg. the template meta tag specifies which template to use). Templation makes no distinction between control data and content because in practice you may want some control to depend on the value of data and vice-versa.

Templation execution phase

Templation is written in PHP, but it can be used to manipulate files containing PHP. Because of this, source file PHP code is not executed inline. Rather an entire output page is constructed and then executed at the end. This provides many benefits including cacheable execution, easier debugging, and complete site exporting. The Templation execution phase is the first part of execution where the majority of Templation code (and widgets) are executed.

c. Philosophy

Templation started life simply named CMS. Indeed Templation makes content easy to manage, but unlike every single content management system on the market, it does so without diluting the collective HTML and CSS knowledge the web design community has built up over the years.

Traditional content management systems attempt to simplify things by building a huge rickety scaffolding and/or mashing pre-fabricated components together to form a site. Yes, non-technical staff are empowered to update the site, but at what cost? The simple beauty of HTML files sitting in a directory structure that mirrors the URL schema is lost forever in a sea of cumbersome web-based forms and database-camouflaged content.

Templation operates on the principle that a natural website directory structure provides a suitable framework to fix 99% of the problems with plainfile web development without resorting to a completely new development methodology. Working with raw HTML and CSS is a lot easier and more flexible than brittle content management systems that crack at the first sign of deviation from the master plan. Templation solves problems for web designers and programmers while leaving the higher level content-development issues to be solved separately.

What Templation is not...

Templation is not a system like Postnuke which builds sites from standard modules, and controls all aspects of navigation and display through the use of complex logic. It's also not like FileNet which provides complex web-based authoring tools and workflow management for diverse corporate content teams. By default Templation has none of the high-level functionality for producing, editing, and maintaining actual page content. Such tools are invaluable for those few websites that are truly gargantuan and require a large staff just to maintain copy. In fact, you can easily install or build those tools on top of Templation seamlessly.

Templation is also not a templating system such as Smarty which allows you to create complex presentation logic for well-defined data. That type of system is optimized for presenting a data model from an application, while Templation excels at merging the various design elements that make up a web page with content whether it comes from a series of flat files or directly out of a web application. The power of Templation does not come from a rich template language, but rather a simple and powerful way of loading data into a template. In Smarty, for example, you spend significant time setting up a complex template only to then be forced to coerce your data into the form that the template needs. By contrast, Templation automatically infers which data to use based on the location where the source files are stored. Web page design and structure tends to be similar with files that are in the same directory, so inferring content this way turns out to save a ton of work.

The majority of content management and templating systems target pretty specific needs. Templation instead focuses on broad issues that every single web designer has faced, even on websites as small 3 or 4 static pages. Think of it as a design management system that assists in setting up and manipulating a website's design infrastructure. Once you get into the rhythm of Templation, the design process is liberated so design or architecture changes late in the game won't be nearly so costly. CSS has delivered more than any other technology in terms of liberating content from presentation, but Templation takes CSS to the next level by allowing even the presentation hooks in the content to be separated out.

d. Concept History

The problem that initially gave rise to Templation occurred during the construction of a 50 page site with a common header and footer. The most common solution is to use a couple server side includes at the top and bottom of each page. Unfortunately, this solution has many maintainability issues, like what if it becomes necessary to move the include files? Editing all those files is a pain, but nothing that can't be solved with a little Perl action. A bigger problem is if each page suddenly requires a unique title. Then the header must be broken into two parts, or replaced with a PHP header_display() function that takes the title as a parameter. Both of these approaches reduce redundancy, but add incredibly specialized code to what should be HTML plain and simple.

But what if you could write a template with an arbitrary number fields that were defined by the individual page's content? This is the kind of functionality associated with traditional PHP templating systems such as Smarty. Such systems offer incredibly powerful ways to define templates, but they require all your content to be in PHP variables already, so you end up with a whole new way of adding pages to your site; one that involves a proprietary syntax and writing clever PHP scripts to minimize your work. In effect these kind of systems are simply output engines; they streamline your PHP code by removing presentational logic. When it comes to an average website such tools are merely obfuscation. Templation's design acknowledges that such systems are usually overkill, instead the goal was to follow in the footsteps of successful technologies like HTML itself that succeeded by keeping it simple.

HTML files and directories form the basis for the vast majority of websites, so why not leverage the information already available to make template building easier? Templation can function entirely based on HTML with extremely simple rules. The result is a system that can solve general redundancy issues on a site quite easily, but can also be extended to generate complex content automatically.

e. Example

In the following example, $webroot refers to your website document root location, and $data refers to the directory where your templation data files are stored (ie. 'data repository' as described in the next section). The files are listed in the order they get accessed so you can get some sense of Templation's flow. Red text indicates items of special significance to templation.

There is a live extended version of this example which is described in Appendix B.