Stencil is a simple and powerful template language for Swift. It provides a syntax similar to Django and Jinja2. If you're familiar with these, you will feel right at home with Stencil.

Example

There are {{ articles.count }} articles.

{% for article in articles %}
  - {{ article.title }} by {{ article.author }}.
{% endfor %}

let context = Context(dictionary: [
    "articles": [
        [ "title": "Migrating from OCUnit to XCTest", "author": "Kyle Fuller" ],
        [ "title": "Memory Management with ARC", "author": "Kyle Fuller" ],
    ]
])

let template = Template(named: "template.stencil")
let result = template.render(context)

if let error = result.error {
    println("There was an error rendering your template (\(error)).")
}

println("\(result.string)")

Philosophy

Stencil follows the same philosophy of Django:

If you have a background in programming, or if you’re used to languages which mix programming code directly into HTML, you’ll want to bear in mind that the Django template system is not simply Python embedded into HTML. This is by design: the template system is meant to express presentation, not program logic.

Templates

Variables

A variable can be defined in your template using the following:

{{ variable }}

Stencil will look up the variable inside the current variable context and evaluate it. When a variable contains a dot, it will try doing the following lookup:

Context lookup
Dictionary lookup
Array lookup (first, last, count, index)
Key value coding lookup

For example, if people was an array:

There are {{ people.count }} people, {{ people.first }} is first person.
Followed by {{ people.1 }}.

Tags

Tags are a mechanism to execute a piece of code which can allows you to have control flow within your template.

{% if variable %}
  {{ variable }} was found.
{% endif %}

A tag can also effect the context and define variables as follows:

{% for item in items %}
  {{ item }}
{% endfor %}

Stencil has a couple of built in tags which are listed below. You will also be able to use the Stencil API to build your own in future versions. This is tracked by a ticket #6.

for

A for loop allows you to iterate over an array found by variable lookup.

{% for item in items %}
  {{ item }}
{% empty %}
  There we're no items.
{% endfor %}

if

{% if variable %}
  The variable was found in the current context.
{% else %}
  The variable was not found.
{% endif %}

ifnot

{% ifnot variable %}
  The variable was NOT found in the current context.
{% else %}
  The variable was found.
{% endif %}

Comments

To comment out part of your template you can use the following syntax:

{# My comment is completely hidden #}

License

Stencil is licensed under the BSD license. See LICENSE for more info.

README.md Unescape Escape

Stencil