Currently in Beta - View old docs

Kitura Stencil

Prerequisites

Step 1: Create a `StencilRoutes.swift` file

Open your `Sources` > `Application` > `Application.swift`

Inside the `postInit()` function add:

initializeStencilRoutes(app: self)

Create a new file called `StencilRoutes.swift` in `Sources` > `Application` > `Routes`

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 StencilTemplateEngine to our router

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 2: 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 3: 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.

Next steps

Coming Soon!

Back to top