Currently in Beta - View old docs

Kitura Stencil

To implement Stencil templating with a Kitura server, we use Kitura-StencilTemplateEngine. This package makes it easy to to create an HTML page with integrated Swift variables.

Step 1: Create your Stencil routes

To use Stencil from a server, we first need to add Kitura-StencilTemplateEngine to our dependencies.

If you don't have a server, follow our Create a server guide.

Next, we need a file for our Stencil routes.

Open your Application.swift file:

open Sources/Application/Application.swift

Inside the postInit() function add:

initializeStencilRoutes(app: self)

Create a new file, called StencilRoutes.swift:

touch Sources/Application/Routes/StencilRoutes.swift

Open your StencilRoutes.swift file:

open Sources/Application/Routes/StencilRoutes.swift

Inside this file, add the framework for our routes code:

import KituraStencil

func initializeStencilRoutes(app: App) {
    // register template engine here
    app.router.get("/stencil") { request, response, next in
        // render response here
        next()
    }
}

Templating is not part of a REST api so it only supported in Raw routes.

Step 2: Add a Stencil template engine

We register a stencil temple engine to our router instance:

app.router.add(templateEngine: StencilTemplateEngine())

The above line of code tells the server on this instance of the router we'd like to use Stencil as the default template engine.

Kitura is capable of having numerous template engines registered to a single instance of a router.

Kitura then provides APIs to select a default template engine to use.

We've just added the Stencil template engine to our router, so now we can use it in a route.

Inside our get route, add the following:

let book = Book(id: 0, title: "A Game of Thrones", price: 14.99, genre: "fantasy")
try response.render("book.stencil", with: book)

Your completed StencilRoutes.swift should now look as follows:

import KituraStencil

func initializeStencilRoutes(app: App) {
    app.router.add(templateEngine: StencilTemplateEngine())
    app.router.get("/stencil") { request, response, next in
        let book = Book(id: 0, title: "A Game of Thrones", price: 14.99, genre: "fantasy")
        try response.render("book.stencil", with: book)
        next()
    }
}

The response.render() method attempts to populate the provided template file with the provided data.

In our case, the file book.stencil template will be populated with the book data and then rendered in the browser on "/book".

This obviously will not work as we haven't created our book.stencil file.

Step 3: Create the template file

By default Kitura looks for template files in a ./Views directory found at the root of the project.

Typically the root of your project is where the .xcodeproj directory is.

Once we are in the root of our project we can create the directory:

mkdir Views

If you would prefer you can create your directory using a UI based approach, such as Finder on Mac.

Then we need to create our template file within the Views directory.

In a terminal run the following:

cd Views && touch book.stencil

Now we have everything we need to start creating our templates.

The last thing we need to do is recreate our Xcode project:

swift package generate-xcodeproj

This is to enable Xcode to pick up the new directory we've just added.

Step 4: Populate the Stencil template file

Stencil is a templating language that has a lot of powerful features, you can learn about them in the Stencil guide.

We first need some template code to populate.

Open the book.stencil file and add the following:

<html>
    <p> Id:     {{ id }}   </p>
    <p> Title: {{ title }} </p>
    <p> Price: {{ price }} </p>
    <p> Genre: {{ genre }} </p>
</html>

Now to test our templating, we first need to start the Kitura server.

Then in a browser open: http://localhost:8080/stencil

In the browser we should see:

Id: 0

Title: A Game of Thrones

Price: 14.99

Genre: "fantasy"

That's it! We've just rendered a simple data type in the browser using Kitura Stencil.

Back to top