Template API

This document describes Stencils Swift API, and not the Swift template language.

Environment

An environment contains shared configuration such as custom filters and tags along with template loaders.

let environment = Environment()

You can optionally provide a loader or extensions when creating an environment:

let environment = Environment(loader: ..., extensions: [...])

Rendering a Template

Environment provides convinience methods to render a template either from a string or a template loader.

let template = "Hello {{ name }}"
let context = ["name": "Kyle"]
let rendered = environment.renderTemplate(string: template, context: context)

Rendering a template from the configured loader:

let context = ["name": "Kyle"]
let rendered = environment.renderTemplate(name: "example.html", context: context)

Loading a Template

Environment provides an API to load a template from the configured loader.

let template = try environment.loadTemplate(name: "example.html")

Loader

Loaders are responsible for loading templates from a resource such as the file system.

Stencil provides a FileSytemLoader which allows you to load a template directly from the file system.

FileSystemLoader

Loads templates from the file system. This loader can find templates in folders on the file system.

FileSystemLoader(paths: ["./templates"])

FileSystemLoader(bundle: [Bundle.main])

DictionaryLoader

Loads templates from a dictionary.

DictionaryLoader(templates: ["index.html": "Hello World"])

Custom Loaders

Loader is a protocol, so you can implement your own compatible loaders. You will need to implement a loadTemplate method to load the template, throwing a TemplateDoesNotExist when the template is not found.

class ExampleMemoryLoader: Loader {
  func loadTemplate(name: String, environment: Environment) throws -> Template {
    if name == "index.html" {
      return Template(templateString: "Hello", environment: environment)
    }

    throw TemplateDoesNotExist(name: name, loader: self)
  }
}

Context

A Context is a structure containing any templates you would like to use in a template. It’s somewhat like a dictionary, however you can push and pop to scope variables. So that means that when iterating over a for loop, you can push a new scope into the context to store any variables local to the scope.

You would normally only access the Context within a custom template tag or filter.

Subscripting

You can use subscripting to get and set values from the context.

context["key"] = value
let value = context["key"]

push()

A Context is a stack. You can push a new level onto the Context so that modifications can easily be poped off. This is useful for isolating mutations into scope of a template tag. Such as {% if %} and {% for %} tags.

context.push(["name": "example"]) {
    // context contains name which is `example`.
}

// name is popped off the context after the duration of the closure.

flatten()

Using flatten() method you can get whole Context stack as one dictionary including all variables.

let dictionary = context.flatten()