Getting Started with Template Kit¶
Template Kit is designed to make implementing a templating language easy by defining a common template structure and handling the entire serialization step.
These docs are for developers interested in implementing a templating language using Template Kit. See Leaf → Getting Started for information about using Leaf.
This package is included with Vapor and exported by default. You will have access to all
TemplateKit APIs when you import
The Template Kit package is lightweight, pure-Swift, and has very few dependencies. This means it can be used as a templating framework for any Swift project—even one not using Vapor.
To include it in your package, add the following to your
// swift-tools-version:4.0 import PackageDescription let package = Package( name: "Project", dependencies: [ ... .package(url: "https://github.com/vapor/template-kit.git", from: "1.0.0"), ], targets: [ .target(name: "Project", dependencies: ["TemplateKit", ... ]) ] )
import TemplateKit to access the APIs.
Let's take a look at how Leaf uses Template Kit to render views.
Assume we have a template
greeting.leaf with the following contents:
This first step in rendering this view is to parse the syntax into an abstract syntax tree (AST). This is the part of view rendering that Leaf is responsible for, since Leaf has a unique syntax.
Leaf does this by creating a
LeafParser that conforms to
greeting.leaf -> LeafParser -> AST
In code, this looks like:
func parse(scanner: TemplateByteScanner) throws -> [TemplateSyntax]
The AST for our example
greeting.leaf file would look something like this:
[ .raw(data: "Hello. "), .tag( name: "capitalize", parameters: [.identifier("name")] ), .raw(data: "!"), ]
Now that Leaf has created an AST, it's job is done! Template Kit will handle converting this AST into a rendered view. All it needs is a
TemplateData to use for filling in any variables.
let data = TemplateData.dictionary(["name": "vapor"])
The above data will be combined with the AST and used by the
TemplateSerializer to create a rendered view.
AST + Data -> TemplateSerializer -> View
Our rendered view will look something like:
All of these steps are handled by
LeafRenderer which conforms to
TemplateRenderer. A template renderer is simply an object that contains both a parser and a serializer. When you implement one, you will get several helpful extensions from Template Kit for free that help load files and cache parsed ASTs. It's what the end user will use to render views.
The entire pipeline looks like this:
LeafRenderer | |----------------------------------------------------------------| greeting.leaf -> LeafParser -> AST -> TemplateSerializer -> View ^ / TemplateData
In code, the method looks like this:
public func render(_ path: String, _ context: TemplateData) -> Future<View>
Check out Template Kit's API docs for detailed information about all of the protocols, structs, and classes Template Kit offers.