Templates

As mentioned on the Source files page, every element in a source file must have a corresponding template. Templates should be placed in the directory design/templates. The template is effectively a function that takes the attributes and content of the element as arguments, and returns the appropriate HTML. Within a template, variable references are indicated by surrounding them with {{ and }}. Information about the source file element is stored in the special variable this. For example, you can refer to the content of the element like this: {{this.content}}. If the element has a name attribute, you could reference it like this: {{this.name}}.

In many cases, a template does nothing more than variable substitution. For example, a template for the event-listing element might look like this:

<section class="event-listing">
  <h1 class="event-listing__name">{{this.name}}</h1>
  <div class="event-listing__date">{{this.month}}/{{this.day}}/{{this.year}}</div>
  <div class="event-listing__location">{{this.location}}</div>
  <div class="event-listing__price">{{this.price}}</div>
  <p class="event-listing__description">
    {{this.content}}
  </p>
</section>

However, as templates are expanded by Jinja, you can do anything that is supported by a Jinja template. For example, it might be convenient to have a short-hand way to create simple tables in a document, something like this:

<table>
      | Hot | Cold
Dry   | 24  | 31
Rainy | 17  | 19
</table>

The following template takes the content of this element and arranges it into a proper HTML table:

<div class="content-table-container">
  <table class="content-table">
    {% for row in this.content.split('\n') %}
    <tr>
      {% for cell in row.split('|') %}
      <td>{{ cell.strip() }}</td>
      {% endfor %}
    </tr>
    {% endfor %}
  </table>
</div>

In certain cases you may find it useful to create a template with the same name as a standard HTML element. This allows you to use that element in your source files, just as you could use it if you were writing HTML directly. However, it also allows you to override the default behavior of that element to fit the needs of your situation. For example, here's an example of overriding the h1 tag:

<h1 class="section1-heading">
  <span class="decorated-text">{{ this.content }}</span>
</h1>

Notice that not only have we applied a CSS class to the element, but we have used two tags rather than one. This allows you to do more sophisticated styling than could be accomplished with CSS classes alone. In this case, it allows us to limit the text decoration to the width of the text, rather than the full width of the page. The big advantage is that all of this complexity is encapsulated in the template. In the source file, you just use the h1 element like you normally would.

Of course, for this to work, you do still need CSS styles. You can use inline styles, but you will lose out on the many advantages of having a separate style sheet. See Using CSS styles for more information about using CSS style sheets.