Kitura Stencil Tutorial: How to make Websites with Swift
Build a web-based frontend for your Kitura API using Stencil, in this server-side Swift tutorial! By David Okun.
It’s a lot of fun building up a back-end API in Swift with Kitura, and testing it with the OpenAPI Explorer, or maybe you’ve gone the distance to build an iOS app to consume your API. It’s totally understandable to want to show this work off to your friends.
However, what if they try to log in as “Leia Organa” through the API Explorer on your machine when you deploy to localhost, and they get annoyed at you for continually asking them to come over? Worse yet… what if they don’t have iPhones?!
In this tutorial on building websites with a Swift templating library named Stencil, you’ll use a pre-built back-end Kitura app for saving emoji info named EmojiJournal in order to:
- Discover how a web-based front-end is structured.
- Learn how Stencil templating works.
- Set up your basic /client route for accessing the front-end on the web.
By the end of this tutorial, you’ll have a working web client that still needs some work, but is ready to go out of the box!
Note: This tutorial assumes you have some experience with using Kitura to build Swift web apps. See Kitura Tutorial: Getting Started With Server-Side Swift if you’re new to Kitura.
Note: This tutorial assumes you have some experience with using Kitura to build Swift web apps. See Kitura Tutorial: Getting Started With Server-Side Swift if you’re new to Kitura.
You’ll also need the following available to you in order to follow along:
- MacOS 10.14 or higher
- Xcode 10.1 or newer
- Homebrew
- PostgreSQL
- Basic familiarity with Terminal, as you’ll use the command line quite a bit
Getting Started
To start, download the starter project materials using the Download Materials button at the top or bottom of this page.
This tutorial is going to contain some work in the following languages:
- HTML (HyperText Markup Language)
- JS (JungleScribble… kidding, JavaScript)
Regardless of your experience working with any of these, I humbly ask you to not be alarmed! I might not go into the deepest depths of explaining everything we write in other languages, but I will include a nugget or two of knowledge about everything you add to your project.
Open the starter project in Finder, and navigate to the EmojiJournalServer/public directory. Open the folder and look at the structure. It should look like so:
This project will not require you to modify these files in any way, so you can largely leave these alone, but you should at least know what is in each directory:
- css: This is an acronym for Cascading Style Sheets. Using CSS is how the different HTML components you will be creating will order and position themselves by reference. You have CSS files for both the emoji-picker component and the main page you will format.
- img: This is short for images. This is nothing more than a folder for static image assets that will go on your web client. I am by no means a web designer, so if you see fit to make changes, go nuts!
- js: The scripts that make your web client run as smoothly as it will. If you edit these, to quote npm (Node Package Manager): I hope you know what you’re doing.
It is good and common practice to load these into a folder called public on your front end. Typically, you could also put your .html files into their own directory here as well. However, you’re going to be working with Stencil, which is a powerful templating library written for Swift, and mostly maintained by Kyle Fuller.
Wait… Templating?
When I say templating, I mean the ability to reproduce multiple variables and components in a repeatable manner that you have the power to format.
Take this for example: Let’s say you wanted to write a webpage that always tells you the current month. A naïve approach to such a task might look like so in HTML:
<!DOCTYPE html>
<html>
<head>
<title>The current month is December!</title>
</head>
</html>
Depending on when you are reading this tutorial, this result might be appropriate, but there’s only approximately an 8.5% chance it is.
That is hardly sustainable; I wouldn’t want to be the web developer responsible for maintaining this! Thanks to Stencil, you now have the ability to pass in a variable, and Stencil will render your template file to spit out the proper date! Your .stencil file would look like so:
<!DOCTYPE html>
<html>
<head>
<title>The current month is {{ currentMonth }}!</title>
</head>
</html>
The main difference here is the inclusion of the {{ currentMonth }}, but notice the curly braces around each end of the variable. Those are the delimiter that Stencil will search for when looking for a place to insert information. Stencil essentially operates on this workflow:
- Prepare data from your API.
- Set up a context: a dictionary of key/value pairs.
- Populate your context with the values you want to display.
- Render a template in your response, using a context.
If you didn’t raise an eyebrow halfway through this list, go back and look at #2. Hopefully, you’re thinking, “Wait a minute… there’s all this focus in Swift on the Codable protocol, and now I have to form a key-value pair dictionary? What gives, David?!” You should know I would never pull one over on you like that — of course you can use Codable!
On the Swift side of things, you need to prepare an object that is either Codable or an array of homogenous Codable objects. You’ll cover the whole flow from front to back shortly, but if you wanted to reduce the above sample to a short code snippet, it might look like this:
struct CurrentMonth: Codable {
var month: String
}
try response.render("home.stencil",
with: CurrentMonth(month: "December"), forKey: "currentMonth")
And, then, in your home.stencil file, you would handle this variable like so:
<!DOCTYPE html>
<html>
<head>
<title>
The current month is {{ currentMonth.month }}!
</title>
</head>
</html>
Notice the slight change in the above example. This is because your Codable object has a property on it titled month. Since Codable handles serializing the JSON for you, Stencil gives you an easy way to read stored properties in your .stencil file.