Every part you need to know concerning the upcoming Leaf template engine replace and migrate your Vapor / Swift codebase.
Vapor
Utilizing Leaf 4 Tau
Earlier than we dive in, let’s make a brand new Vapor challenge with the next bundle definition.
import PackageDescription
let bundle = Package deal(
title: "myProject",
platforms: [
.macOS(.v10_15)
],
dependencies: [
.package(url: "https://github.com/vapor/vapor.git", from: "4.30.0"),
.package(url: "https://github.com/vapor/leaf", .exact("4.0.0-tau.1")),
.package(url: "https://github.com/vapor/leaf-kit", .exact("1.0.0-tau.1.1")),
],
targets: [
.target(name: "App", dependencies: [
.product(name: "Vapor", package: "vapor"),
.product(name: "Leaf", package: "leaf"),
]),
.goal(title: "Run", dependencies: ["App"]),
.testTarget(title: "AppTests", dependencies: [
.target(name: "App"),
.product(name: "XCTVapor", package: "vapor"),
])
]
)
The very very first thing I would like to point out you is that we have now a brand new render technique. Previously we have been in a position to make use of the req.view.render operate to render our template information. Think about the next actually easy index.leaf file with two context variables that we’ll give show actual quickly.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta title="viewport" content material="width=device-width, initial-scale=1">
<title>#(title)</title>
</head>
<physique>
#(physique)
</physique>
</html>
Now in our Vapor codebase we may use one thing like this to render the template.
import Vapor
import Leaf
public func configure(_ app: Software) throws {
app.views.use(.leaf)
app.get() { req -> EventLoopFuture<View> in
struct Context: Encodable {
let title: String
let physique: String
}
let context = Context(title: "Leaf 4", physique:"Good day Leaf Tau!")
return req.view.render("index", context)
}
}
We will use an Encodable object and move it round as a context variable. This can be a handy approach of offering values for our Leaf variables. Earlier than we proceed I’ve to let you know that every one of this may proceed to work in Leaf Tau and you do not have to make use of the brand new strategies. 👍
New render strategies
So let me present you the very same factor utilizing the brand new API.
import Vapor
import Leaf
public func configure(_ app: Software) throws {
app.views.use(.leaf)
app.get() { req -> EventLoopFuture<View> in
let context: LeafRenderer.Context = [
"title": "Leaf 4",
"body": "Hello Leaf Tau!",
]
return req.leaf.render(template: "index", context: context)
}
}
That is not a giant deal you would say at first sight. Effectively, the factor is that this new technique gives type-safe values for our templates and that is simply the tip of the iceberg. You need to neglect concerning the view property on the request object, since Leaf began to outgrow the view layer in Vapor.
import Vapor
import Leaf
public func configure(_ app: Software) throws {
app.views.use(.leaf)
app.get() { req -> EventLoopFuture<View> in
let title = "Leaf Tau"
let context: LeafRenderer.Context = [
"title": "Leaf 4",
"body": .string("Hello (name)!"),
]
return req.leaf.render(template: "index",
from: "default",
context: context,
choices: [.caching(.bypass)])
}
}
When you take a more in-depth have a look at this comparable instance, you discover out that the context object and the values are representable by numerous sorts, but when we attempt to use an interpolated string, we have now to be a little bit bit extra kind particular. A LeafRenderer.Context object is considerably a [String: LeafData] alias the place LeafData has a number of static strategies to initialize the built-in fundamental Swift sorts for Leaf. That is the place the type-safety characteristic is available in Tau. You should utilize the static LeafData helper strategies to ship your values as given sorts. 🔨
The from parameter is usually a LeafSource key, if you’re utilizing a number of template areas or file sources then you’ll be able to render a view utilizing a particular one, ignoring the supply loading order. There may be one other render technique with out the from parameter that’ll use the default search order of sources.
There’s a new argument that you should use to set predefined choices. You possibly can disable the cache mechanism with the .caching(.bypass) worth or the built-in warning message by way of .missingVariableThrows(false) if a variable just isn’t outlined in your template, however you are attempting to make use of it. You possibly can replace the timeout utilizing .timeout(Double) or the encoding through .encoding(.utf8) and grant entry to some nasty entities by together with the .grantUnsafeEntityAccess(true) worth plus there’s a embeddedASTRawLimit choice. Extra about this afterward.
It’s also attainable to disable Leaf cache globally by way of the LeafRenderer.Context property:
if !app.setting.isRelease {
LeafRenderer.Choice.caching = .bypass
}
If the cache is disabled Leaf will re-parse template information each time you attempt to render one thing. Something that may be configured globally for LeafKit is marked with the @LeafRuntimeGuard property wrapper, you’ll be able to change any of the settings at utility setup time, however they’re locked as quickly as a LeafRenderer is created. 🔒
Context and information illustration
You possibly can conform to the LeafDataRepresentable protocol to submit a customized kind as a context worth. You simply should implement one leafData property.
struct Consumer {
let id: UUID?
let electronic mail: String
let birthYear: Int?
let isAdmin: Bool
}
extension Consumer: LeafDataRepresentable {
var leafData: LeafData {
.dictionary([
"id": .string(id?.uuidString),
"email": .string(email),
"birthYear": .int(birthYear),
"isAdmin": .bool(isAdmin),
"permissions": .array(["read", "write"]),
"empty": .nil(.string),
])
}
}
As you’ll be able to see there are many LeafData helper strategies to signify Swift sorts. Each single kind has built-in optionally available assist, so you’ll be able to ship nil values with out spending extra effort on worth checks or nil coalescing.
app.get() { req -> EventLoopFuture<View> in
let consumer = Consumer(id: .init(),
electronic mail: "[email protected]",
birthYear: 1980,
isAdmin: false)
return req.leaf.render(template: "profile", context: [
"user": user.leafData,
])
}
You possibly can assemble a LeafDataRepresentable object, however you continue to have to make use of the LeafRenderer.Context as a context worth. Luckily that kind might be expressed utilizing a dictionary the place keys are strings and values are LeafData sorts, so this may scale back the quantity of code that it’s a must to kind.
Constants, variables, nil coalescing
Now let’s transfer away a little bit bit from Swift and speak concerning the new options in Leaf. In Leaf Tau you’ll be able to outline variables utilizing template information with actual dictionary and array assist. 🥳
#var(x = 2)
<p>2 + 2 = #(x + 2)</p>
<hr>
#let(consumer = ["name": "Guest"])
<p>Good day #(consumer.title)</p>
<hr>
#(optionally available ?? "fallback")
Similar to in Swift, we are able to create variables and constants with any of the supported sorts. Whenever you inline a template variables might be accessed in each templates, that is fairly useful as a result of you do not have to repeat the identical code time and again, however you should use variables and reuse chunks of Leaf code in a clear and environment friendly approach. Let me present you the way this works.
It’s also attainable to make use of the coalescing operator to offer fallback values for nil variables.
Outline, Consider, Inline
One of many greatest debate in Leaf is the entire template hierarchy system. In Tau, all the method is rebuilt beneath the hood (the entire thing is extra highly effective now), however from the end-user perspective just a few key phrases have modified.
Inline
Prolong is now changed with the brand new inline block. The inline technique actually places the content material of a template into one other. You possibly can even use uncooked values in the event you do not need to carry out different operations (akin to evaluating Leaf variables and tags) on the inlined template.
<!-- index.leaf -->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta title="viewport" content material="width=device-width, initial-scale=1">
<title>Leaf 4</title>
</head>
<physique>
#inline("house", as: uncooked)
</physique>
</html>
<!-- house.leaf -->
<h1>Good day Leaf Tau!</h1>
As you’ll be able to see we’re merely placing the content material of the house template into the physique part of the index template.
Now it is extra fascinating once we skip the uncooked half and we inline a daily template that incorporates different expressions. We’re going to flip issues just a bit bit and render the house template as an alternative of the index.
app.get() { req -> EventLoopFuture<View> in
req.leaf.render(template: "house", context: [
"title": "Leaf 4",
"body": "Hello Leaf Tau!",
])
}
So how can I reuse my index template? Ought to I merely print the physique variable and see what occurs? Effectively, we are able to strive that…
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta title="viewport" content material="width=device-width, initial-scale=1">
<title>#(title)</title>
</head>
<physique>
#(physique)
</physique>
</html>
<!-- house.leaf -->
<h1>Good day Leaf Tau!</h1>
#inline("index")
Wait a minute… this code just isn’t going to work. Within the house template first we print the physique variable, then we inline the index template and print its contents. That is not what we wish. I need to use the contents of the house template and place it in between the physique tags. 💪
Consider
Meet consider, a operate that may consider a Leaf definition. You possibly can consider this as a block variable definition in Swift. You possibly can create a variable with a given title and afterward name that variable (consider) utilizing parentheses after the title of the variable. Now you are able to do the identical skinny in Leaf through the use of the consider key phrase or straight calling the block like a operate.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta title="viewport" content material="width=device-width, initial-scale=1">
<title>#(title)</title>
</head>
<physique>
#consider(bodyBlock) (# or you should use the `#bodyBlock()` syntax #)
</physique>
</html>
On this template we are able to consider the bodyBlock and afterward we’ll have the ability to outline it elsewhere.
Outline
Definitions. Lastly arrived to the final element that we’ll have to compose templates. Now we are able to create our physique block within the house template.
#outline(bodyBlock):
<h1>#(physique)</h1>
#enddefine
#inline("index")
Now in the event you reload the browser (Leaf cache have to be disabled) the whole lot ought to work as it’s anticipated. Magic… or science, no matter, be at liberty to decide on one. 💫
Particular thanks goes to tdotclare who labored day and evening to make Leaf higher. 🙏
So what is going on on right here? The #outline(bodyBlock) part is accountable for constructing a block variable referred to as bodyBlock that’s callable and we are able to consider it afterward. We merely print out the physique context variable inside this block, the physique variable is a context variable coming from Swift, that is fairly easy. Subsequent we inline the index template (think about copy-pasting total content material of the index template into the house template) which can print out the title context variable and evaluates the bodyBlock. The bodyBlock will probably be accessible since we have simply outlined it earlier than our inline assertion. Simple peasy. 😝
<!-- var, let -->
#var(x = 10)
#let(foo = "bar")
<!-- outline -->
#outline(resultBlock = x + 1)
#outline(bodyBlock):
<h2>Good day, world!</h2>
<p>I am a multi-line block definition</p>
#endblock
<!-- consider -->
#consider(resultBlock)
#bodyBlock()
I am actually glad about these adjustments, as a result of Leaf is heading into the proper route, and people individuals who haven’t used the pre-released Leaf 4 variations but these adjustments will not trigger that a lot bother. This new method follows extra like the unique Leaf 3 conduct.
Goodbye tags. Good day entities!
Nothing is a tag anymore, however they’re separated to the next issues:
- Blocks (e.g. #for, #whereas, #if, #elseif, #else)
- Capabilities (e.g. #Date, #Timestamp, and so forth.)
- Strategies (e.g. .rely(), .isEmpty, and so forth.)
Now you can create your very personal capabilities, strategies and even blocks. 🔥
public struct Good day: LeafFunction, StringReturn, Invariant {
public static var callSignature: [LeafCallParameter] { [.string] }
public func consider(_ params: LeafCallValues) -> LeafData {
guard let title = params[0].string else {
return .error("`Good day` have to be referred to as with a string parameter.")
}
return .string("Good day (title)!")
}
}
public func configure(_ app: Software) throws {
LeafConfiguration.entities.use(Good day(), asFunction: "Good day")
}
Now you should use this operate in your templates like this:
#Good day("Leaf Tau")
You possibly can occasion overload the identical operate with totally different argument labels
public struct HelloPrefix: LeafFunction, StringReturn, Invariant {
public static var callSignature: [LeafCallParameter] { [
.string(labeled: "name"),
.string(labeled: "prefix", optional: true, defaultValue: "Hello")]
}
public func consider(_ params: LeafCallValues) -> LeafData {
guard let title = params[0].string else {
return .error("`Good day` have to be referred to as with a string parameter.")
}
let prefix = params[1].string!
return .string("(prefix) (title)!")
}
}
public func configure(_ app: Software) throws {
LeafConfiguration.entities.use(Good day(), asFunction: "Good day")
LeafConfiguration.entities.use(HelloPrefix(), asFunction: "Good day")
}
This manner you should use a number of variations of the identical performance.
#Good day("Leaf Tau")
#Good day(title: "Leaf Tau", prefix: "Hello")
This is one other instance of a customized Leaf technique:
public struct DropLast: LeafNonMutatingMethod, StringReturn, Invariant {
public static var callSignature: [LeafCallParameter] { [.string] }
public func consider(_ params: LeafCallValues) -> LeafData {
.string(String(params[0].string!.dropLast()))
}
}
public func configure(_ app: Software) throws {
LeafConfiguration.entities.use(DropLast(), asMethod: "dropLast")
}
You possibly can outline your individual Leaf entities (extensions) through protocols. You do not have to recollect all of them, as a result of there may be numerous them, however that is the sample that you need to search for Leaf*[Method|Function|Block] for the return sorts: [type]Return. If you do not know invariant is a operate that produces the identical output for a given enter and it has no unwanted effects.
You possibly can register these entities as[Function|Method|Block] by way of the entities property. It will take some time till you get acquainted with them, however luckily Leaf 4 comes with fairly a very good set of built-in entities, hopefully the official documentation will cowl most of them. 😉
public struct Path: LeafUnsafeEntity, LeafFunction, StringReturn {
public var unsafeObjects: UnsafeObjects? = nil
public static var callSignature: [LeafCallParameter] { [] }
public func consider(_ params: LeafCallValues) -> LeafData {
guard let req = req else { return .error("Wants unsafe entry to Request") }
return .string(req.url.path)
}
}
public func configure(_ app: Software) throws {
LeafConfiguration.entities.use(Path(), asFunction: "Path")
}
Oh, I virtually forgot to say that in the event you want particular entry to the app or req property it’s a must to outline an unsafe entity, which will probably be thought of as a nasty apply, however luckily we have now one thing else to switch the necessity for accessing this stuff…
Scopes
If it’s worthwhile to move particular issues to your Leaf templates it is possible for you to to outline customized scopes.
extension Request {
var customLeafVars: [String: LeafDataGenerator] {
[
"url": .lazy([
"isSecure": LeafData.bool(self.url.scheme?.contains("https")),
"host": LeafData.string(self.url.host),
"port": LeafData.int(self.url.port),
"path": LeafData.string(self.url.path),
"query": LeafData.string(self.url.query)
]),
]
}
}
extension Software {
var customLeafVars: [String: LeafDataGenerator] {
[
"isDebug": .lazy(LeafData.bool(!self.environment.isRelease && self.environment != .production))
]
}
}
struct ScopeExtensionMiddleware: Middleware {
func reply(to req: Request, chainingTo subsequent: Responder) -> EventLoopFuture<Response> {
do {
strive req.leaf.context.register(mills: req.customLeafVars, toScope: "req")
strive req.leaf.context.register(mills: req.utility.customLeafVars, toScope: "app")
}
catch {
return req.eventLoop.makeFailedFuture(error)
}
return subsequent.reply(to: req)
}
}
public func configure(_ app: Software) throws {
app.middleware.use(ScopeExtensionMiddleware())
}
Lengthy story quick, you’ll be able to put LeafData values right into a customized scope, the good factor about this method is that they are often lazy, so Leaf will solely compute the corresponding values if when are getting used. The query is, how will we entry the scope? 🤔
<ul>
<li><b>ctx:</b>: #($context)</li>
<li><b>self:</b>: #(self)</li>
<li><b>req:</b>: #($req)</li>
<li><b>app:</b>: #($app)</li>
</ul>
You need to know that self is an alias to $context, and you may entry your individual context variables utilizing the $ signal. You too can construct your individual LeafContextPublisher object that may use to change the scope.
remaining class VersionInfo: LeafContextPublisher {
let main: Int
let minor: Int
let patch: Int
let flags: String?
init(main: Int, minor: Int, patch: Int, flags: String? = nil) {
self.main = main
self.minor = minor
self.patch = patch
self.flags = flags
}
var versionInfo: String {
let model = "(main).(minor).(patch)"
if let flags = flags {
return model + "-" + flags
}
return model
}
lazy var leafVariables: [String: LeafDataGenerator] = [
"version": .lazy([
"major": LeafData.int(self.major),
"minor": LeafData.int(self.minor),
"patch": LeafData.int(self.patch),
"flags": LeafData.string(self.flags),
"string": LeafData.string(self.versionInfo),
])
]
}
public func configure(_ app: Software) throws {
app.views.use(.leaf)
app.middleware.use(LeafCacheDropperMiddleware())
app.get(.catchall) { req -> EventLoopFuture<View> in
var context: LeafRenderer.Context = [
"title": .string("Leaf 4"),
"body": .string("Hello Leaf Tau!"),
]
let versionInfo = VersionInfo(main: 1, minor: 0, patch: 0, flags: "rc.1")
strive context.register(object: versionInfo, toScope: "api")
return req.leaf.render(template: "house", context: context)
}
}
What if you wish to prolong a scope? No drawback, you are able to do that by registering a generator
extension VersionInfo {
var extendedVariables: [String: LeafDataGenerator] {[
"isRelease": .lazy(self.major > 0)
]}
}
let versionInfo = VersionInfo(main: 1, minor: 0, patch: 0, flags: "rc.1")
strive context.register(object: versionInfo, toScope: "api")
strive context.register(mills: versionInfo.extendedVariables, toScope: "api")
return req.leaf.render(template: "house", context: context)
There may be an app and req scope accessible by default, so you’ll be able to prolong these by way of an extension that may return a [String: LeafDataGenerator] variable.
Abstract
As you’ll be able to see Leaf improved quite a bit in comparison with the earlier variations. Even within the beta / rc interval of the 4th main model of this async template engine introduced us so many nice stuff.
Hopefully this text will show you how to through the migration course of, and I consider that it is possible for you to to make the most of most of those built-in functionalities. The model new render and context mechanism offers us extra flexibility with out the necessity of declaring extra native buildings, Leaf variables and the redesigned hierarchy system will assist us to design much more highly effective reusable templates. By means of entity and the scope API we will deliver Leaf to a very new degree. 🍃
