Template inheritance

What is template inheritance

The most powerful – and thus the most complex – part of Outlast Framework’s template engine is template inheritance. Template inheritance allows you to build a base “skeleton” template that contains all the common elements of your site and defines blocks that child templates can override.

This concept was originally inspired by the Django Framework, but has since been implemented by Smarty and Twig and other PHP template systems.

A real-world example

It’s easiest to understand template inheritance by starting with an example:

This template, which we’ll call base.html, defines a simple HTML skeleton document that you might use for a simple two-column page. It’s the job of “child” templates to fill the empty blocks with content.

In this example, the block tag defines three blocks that child templates can fill in. All the block tag does is to tell the template engine that a child template may override those portions of the template.

A child template might look like this:

The extends tag is the key here. It tells the template engine that this template “extends” another template. When the template system evaluates this template, first it locates the parent – in this case, “base.html”.

At that point, the template engine will notice the three block tags in base.html and replace those blocks with the contents of the child template. Depending on the value of blog_entries, the output might look like:

Adding contents to blocks

By default when you override a block, its contents is replaced. But sometimes you want to add to a parent block’s contents instead of replacing it. This is when the {% parentblock %} tag comes in handy.

Template hierarchy

You can use the plugin hierarchy system to create complex template hierarchies that build on one another and follow the DRY principle as much as humanly possible.

When you create a file with the same name as one found in plugin, Outlast Framework will always load up the one which is on the top level hierarchy. So if you have /plugins/news/app/view/news_list.html and you create a file named /app/view/news_list.html, this file will override the one in plugins because the local /app folder is more important in the app hieararchy than /plugins/news/.

Template decoration

Outlast Framework supports template decoration which is more advanced, inter-plugin use of template inheritance. For details, check out the full documentation on template decoration here.