Skip Navigation

Creating Reason Templates

How Reason themes and templates work

Before you create a custom Reason template, it is useful to understand how Reason's templating system works.

  • Template: The HTML framework for a Reason page is generated by a template. The template includes all the HTML that you want shared between all the pages that share that template. It might include common banners, footers, and other elements that do not vary from page to page. The template defines locations on the page where modules can go.
  • Page types: Each Reason page has a page type. A page type maps page locations to modules. In essence, it says "this module should go in this page location and this other module should go in this page location."
  • Modules: Modules are fairly self-contained units of functionality. The site navigation, for example, is a module, as is the page content or an events calendar. They can be simple, or they can act as small applications. Each module produces its own self-contained block of XHTML, and may include its own stylesheet (which you can override in a theme.)
  • Theme: A theme is a combination of a template and a particular stylesheet. Because it can be so readily reskinned with CSS, a good, richly marked-up semantic XHTML template can often be the base for a large number of distinct themes.

For the visually-inclined, here is a graphic representation of the system:

 Templates Schematic

You will note that a Reason template does not have any control over the XHTML produced by the modules. Each module is entirely responsible for producing valid, semantic XHTML. Some modules have their own internal templating systems to allow easy reworking of their XHTML output, while others can be extended and overloaded to modify their output. We won't go any further into modifying the XHTML output of modules in this tutorial, however.

One theme per site

At the time of this writing (Feb. 2009) all pages in a Reason site must have the same theme. Of course, pages may have different modules, in different locations on the page, but if you want different pages in the same site to have different template XHTML, you will need to either put some conditional logic in your template, or split a set of pages off into a separate site.

Creating a new Reason theme, using an existing template

 This is covered in How to Set Up a Reason Theme.

Creating a new Reason template

1. Create a new file in reason_4.0/lib/local/minisite_templates/sample.php:

<?php

// Include the base template, which you will be extending
reason_include_once( 'minisite_templates/default.php' );

// Register this new template with Reason
$GLOBALS[ '_minisite_template_class_names' ][ basename( __FILE__) ] = 'SampleTemplate';

// Define the template as extending the base template
class SampleTemplate extends MinisiteTemplate
{
}
?>

You now have your template file. Right now it does exactly the same thing as the base template. Before we make any changes, let's build a theme with this template so we can apply it to a site.

2. Create a Minisite Template entity in Reason. Log in to Reason, go to the Master Admin, and add a new Minisite Template. Its name should be the same as the filename, but without the .php. So, in this case, we'll enter "sample" as the name of the minisite template. Save & Finish.

3. We'll set up a theme entity in Reason. Go to Themes in Master Admin and create a new theme. Name it whatever you want, and choose the template you just created. This is where we would attach the CSS that makes for a full-fledged theme; see How to Set up a Reason Theme for more information about that. Finish the theme.

4. Assign your new theme to a Reason site. Create a new site or edit an existing site, and change the theme to your new one. Unless you attached some CSS to the theme, the output of pages from the site will be linear and have no styles applied. However, Reason will be using the your new template, and any changes you make to this template will be reflected in the XHTML.

At this point you have two ways to go: you can make minimal changes to the default template, or you can create a new template from scratch. Which way you go is up to you; hopefully this chart will help your decision-making process:

Method Pros Cons
Minimal Updates
  • Changes to base template often inherited
  • May only need to overload a few small methods
  • Less need to duplicate code
  • Requires better understanding of the base template class and of PHP inheritance
  • Minor changes to base class may cause future incompatibilities or unexpected behavior; more testing will likely be needed upon upgrades
  • Harder to see where template HTML is being generated (split up between custom template and base template)
Template-from-scratch
  • Easier to see all HTML in one file
  • Less need to understand PHP inheritance
  • More self-contained; less likely to conflict with upgrades
  • Will not inherit upgrades from base template
  • Will likely duplicate code with the base template
  • May need deeper understanding of Reason API to build sophisticated template elements

 The best approach probably lies somewhere between the two poles. If you are mostly happy with the XHTML produced by the base template, you may want to err on the minimal side, while if you want to do something radically different from the base template it will probably be easier to build it from scratch. You can also aim for a middle ground, generating the majority of the HTML framework in your new class, but relying on inherited methods for complex aspects like building the page title or assembling breadcrumbs.

Here are examples of two types of templates. The minimal one just chose an arbitrary section of the default template to customize; the from-scratch one takes care of the whole output, from doctype to </html>.