Template Inheritance and Inclusion

rrouse edited this page Nov 7, 2011 · 1 revision

Template Inheritance and Inclusion

All but the simplest web applications can benefit from re-using view logic. This page describes your options (some features require Chicago Boss 0.5 or later).

Template inheritance

Templates can inherit from one another. The parent template should include a number of named placeholder blocks, like this:

view/something/parent.html:


<html>
  <title>{% block title %}title goes here...{% endblock %}</title>
</html>

Then the child template can extend the parent using the “extends” tag, and specify what to put in the named blocks, like so:


{% extends "view/something/parent.html" %}
{% block title %}Welcome!{% endblock %}

When the child template is rendered, the result will be:


<html>
  <title>Welcome!</title>
</html>

The template language supports an arbitrary number of levels of inheritance. Child templates simply override the blocks of the parent templates, or use the blocks in the parent template if none is defined.

Including with context: {% include %} and {% ssi ... parsed %}

To directly include a template from another template, the “include” tag can be useful. The “include” tag takes a string literal that says where the included template can be found


{% include "view/something/navigation.html" %}

All of the variables remain in scope, and additional variables can be passed using the “with” keyword:


{% include "view/something/navigation.html" with admin=0 %}

When used with the “parsed” keyword, the “ssi” tag behaves the same as “include”, but it is not possible to pass variables. Example:


{% ssi "view/something/navigation.html" parsed %}

Templates are included at compile-time, and their paths must be specified as a string literal.

Including without context: {% include ... only %}

To include a template without providing access to all the variables currently in scope, use the “only” keyword:


{% include "view/something/navigation.html" with user=user only %}

Again, the path to the included template must be provided as a string literal.

Including without parsing: {% ssi %}

Without the “parsed” keyword, the “ssi” tag can be used to directly include a file at run-time. As such, it can be passed a variable rather than a string literal. However, the included file is not evaluated as template code. Example:


{% with file_path="/path/to/some/file" %}
    {% ssi file_path %}
{% endwith %}