mirror of https://github.com/vapor/docs.git
122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
# Getting Started with Template Kit
|
|
|
|
Template Kit ([vapor/template-kit](https://github.com/vapor/template-kit)) is a framework for implementing templating languages in Swift. It is currently used to power Leaf ([vapor/leaf](https://github.com/vapor/leaf)) and hopefully more languages in the future.
|
|
|
|
Template Kit is designed to make implementing a templating language easy by defining a common template structure and handling the entire serialization step.
|
|
|
|
!!! warning
|
|
These docs are for developers interested in implementing a templating language using Template Kit. See [Leaf → Getting Started](../leaf/getting-started.md) for information about using Leaf.
|
|
|
|
## Vapor
|
|
|
|
This package is included with Vapor and exported by default. You will have access to all `TemplateKit` APIs when you import `Vapor`.
|
|
|
|
```swift
|
|
import Vapor
|
|
```
|
|
|
|
## Standalone
|
|
|
|
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 `Package.swift` file.
|
|
|
|
```swift
|
|
// 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", ... ])
|
|
]
|
|
)
|
|
```
|
|
|
|
Use `import TemplateKit` to access the APIs.
|
|
|
|
|
|
## Overview
|
|
|
|
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:
|
|
|
|
```leaf
|
|
Hello, #capitalize(name)!
|
|
```
|
|
|
|
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 [`TemplateParser`](https://api.vapor.codes/template-kit/latest/TemplateKit/Protocols/TemplateParser.html).
|
|
|
|
|
|
```
|
|
greeting.leaf -> LeafParser -> AST
|
|
```
|
|
|
|
In code, this looks like:
|
|
|
|
```swift
|
|
func parse(scanner: TemplateByteScanner) throws -> [TemplateSyntax]
|
|
```
|
|
|
|
The AST for our example `greeting.leaf` file would look something like this:
|
|
|
|
```swift
|
|
[
|
|
.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.
|
|
|
|
```swift
|
|
let data = TemplateData.dictionary(["name": "vapor"])
|
|
```
|
|
|
|
The above data will be combined with the AST and used by the [`TemplateSerializer`](https://api.vapor.codes/template-kit/latest/TemplateKit/Classes/TemplateSerializer.html) to create a rendered view.
|
|
|
|
```
|
|
AST + Data -> TemplateSerializer -> View
|
|
```
|
|
|
|
Our rendered view will look something like:
|
|
|
|
```html
|
|
Hello, Vapor!
|
|
```
|
|
|
|
All of these steps are handled by `LeafRenderer` which conforms to [`TemplateRenderer`](https://api.vapor.codes/template-kit/latest/TemplateKit/Protocols/TemplateRenderer.html). 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](https://api.vapor.codes/template-kit/latest/TemplateKit/Protocols/TemplateRenderer.html#/s:11TemplateKit0A8RendererPAAE6renderXeXeF) looks like this:
|
|
|
|
```swift
|
|
public func render(_ path: String, _ context: TemplateData) -> Future<View>
|
|
```
|
|
|
|
Check out Template Kit's [API docs](https://api.vapor.codes/template-kit/latest/TemplateKit/index.html) for detailed information about all of the protocols, structs, and classes Template Kit offers.
|
|
|
|
|