Skip to content

Templating

Jump to bottom
Thane Thomson edited this page Jun 27, 2016 · 9 revisions

Statik uses Jinja2 as its templating engine, so if you're familiar with Django's templating engine it'll be pretty easy to get into using Statik's.

This guide will only cover the basics of Jinja2 templating. For more details, the Jinja2 Template Designer Documentation will help.

Variables

One of the most powerful features of any templating engine is its ability to embed variable values when rendering the templates. Statik template variables can come from two different places:

  1. View context - Every view can also define context variables (both static and dynamic). See the Views documentation on how to configure views.
  2. Project context - In your config.yml file within your project, you can define a context variable with both static and dynamic context. See the Project configuration documentation for more details.

The above order also gives the order of precedence for your variables (i.e. if a view context variable and project context variable both have the same name, view variables will override project variables).

Static Context Variables

When defining static context variables, their exact value will be inserted into your template when rendering. Say, for example, your config.yml file defines the following static context:

# config.yml
# ...
context:
  static:
    site-title: This is my page title!

And say, for example, your template looks like this:

<!DOCTYPE html>
<html>
<head><title>{{ site_title }}</title></head>
<body>
  <!-- page body goes here... -->
</body>
</html>

When your template is rendered, it will contain the following HTML content:

<!DOCTYPE html>
<html>
<head><title>This is my page title!</title></head>
<body>
  <!-- page body goes here... -->
</body>
</html>

Dynamic Context Variables

Dynamic context variables are probably the most powerful feature of Statik, where you can define SQLAlchemy queries to query your project's data in versatile ways to insert into your templates.

Here's an example config.yml file that defines a global dynamic variable called authors, which is effectively a string containing a SQLAlchemy query. This query is executed when Statik builds your project, prior to rendering your views.

# config.yml
# ...
context:
  dynamic:
    authors: session.query(Author).order_by(Author.last_name.asc()).all()

It's Python Code!

The first thing to notice here is that we're writing actual Python code in our dynamic variables. One could use Python features such as list comprehension here, lambdas, etc. The result of whatever we write here gets put directly in to the dynamic variable authors (technically, this means we could just write straight Python code here, such as mathematical operations and the like, but it's generally more versatile to use this to query our in-memory SQLAlchemy database).

Accessible Global Variables

The second thing to notice here is that there are many variables and classes exposed when executing the Python code. For one, there's a session variable that we're using in the query that is exposed from the global scope - this is a standard SQLAlchemy session object.

Next, you'll see that your Author model is exposed as a global variable and is accessible from your dynamic context variables too. In fact, all of your models are represented in global scope by SQLAlchemy models derived from a common Base object. See the SQLAlchemy ORM Tutorial for more details.

Dynamic Context Variables Example

Say, for example, you've got 2 instances of your Author model:

# data/Author/michael.yml
first-name: Michael
last-name: Anderson
email: manderson@somewhere.com

and

# data/Author/andrew.yml
first-name: Andrew
last-name: Michaels
email: amichaels@somewhere.com

And you've got a template that makes use of your authors dynamic context variable as follows:

<!-- ... -->

<ul class="authors-list">
  {% for author in authors %}
    <li><a href="mailto:{{ author.email }}">{{ author.first_name }} {{ author.last_name }}</a></li>
  {% endfor %}
</ul>

<!-- ... -->

This will ultimately render to the following HTML code:

<!-- ... -->

<ul class="authors-list">
  <li><a href="mailto:manderson@somewhere.com">Michael Anderson</a></li>
  <li><a href="mailto:amichaels@somewhere.com">Andrew Michaels</a></li>
</ul>

<!-- ... -->
Clone this wiki locally