What’s new in Leaf 4 (Tau)?


The whole lot it’s best to know in regards to the upcoming Leaf template engine replace and how one can migrate your Vapor / Swift codebase.

Vapor

Utilizing Leaf 4 Tau

Earlier than we dive in, let’s make a brand new Vapor mission with the next package deal definition.



import PackageDescription

let package deal = 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 indicate you is that now we have a brand new render methodology. Up to now we have been ready to make use of the req.view.render perform to render our template information. Contemplate 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: Utility) 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:"Hey Leaf Tau!")
        return req.view.render("index", context)
    }
}

We are able to use an Encodable object and move it round as a context variable. This can be a handy manner of offering values for our Leaf variables. Earlier than we proceed I’ve to inform you that every one of it will 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: Utility) 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 an enormous deal you might say at first sight. Effectively, the factor is that this new methodology supplies type-safe values for our templates and that is simply the tip of the iceberg. It’s best to overlook in regards to 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: Utility) 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)])
    }
}

In case you take a better have a look at this comparable instance, you discover out that the context object and the values are representable by varied sorts, but when we attempt to use an interpolated string, now we have to be a bit of bit extra sort 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 need to use the static LeafData helper strategies to ship your values as given sorts. 🔨

The from parameter generally is a LeafSource key, in case you are utilizing a number of template places or file sources then you possibly can render a view utilizing a selected one, ignoring the supply loading order. There may be one other render methodology with out the from parameter that’ll use the default search order of sources.


There’s a new argument that you need to use to set predefined choices. You’ll be able to disable the cache mechanism with the .caching(.bypass) worth or the built-in warning message by .missingVariableThrows(false) if a variable is just not outlined in your template, however you are attempting to make use of it. You’ll be able to 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 in a while.


It is usually doable to disable Leaf cache globally by the LeafRenderer.Context property:

if !app.atmosphere.isRelease {
    LeafRenderer.Possibility.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 possibly can change any of the settings at utility setup time, however they’re locked as quickly as a LeafRenderer is created. 🔒




Context and knowledge illustration

You’ll be able to conform to the LeafDataRepresentable protocol to submit a customized sort as a context worth. You simply need to implement one leafData property.

struct Person {
    let id: UUID?
    let e-mail: String
    let birthYear: Int?
    let isAdmin: Bool
}
extension Person: 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 possibly can see there are many LeafData helper strategies to symbolize Swift sorts. Each single sort has built-in non-obligatory help, so you possibly can ship nil values with out spending extra effort on worth checks or nil coalescing.

app.get() { req -> EventLoopFuture<View> in
    let person = Person(id: .init(),
                e-mail: "[email protected]",
                birthYear: 1980,
                isAdmin: false)

    return req.leaf.render(template: "profile", context: [
        "user": user.leafData,
    ])
}

You’ll be able to assemble a LeafDataRepresentable object, however you continue to have to make use of the LeafRenderer.Context as a context worth. Happily that sort may be expressed utilizing a dictionary the place keys are strings and values are LeafData sorts, so it will scale back the quantity of code that it’s important to sort.



Constants, variables, nil coalescing

Now let’s transfer away a bit of bit from Swift and discuss in regards to the new options in Leaf. In Leaf Tau you possibly can outline variables utilizing template information with actual dictionary and array help. 🥳

#var(x = 2)
<p>2 + 2 = #(x + 2)</p>
<hr>
#let(person = ["name": "Guest"])
<p>Hey #(person.title)</p>
<hr>
#(non-obligatory ?? "fallback")

Identical to in Swift, we will create variables and constants with any of the supported sorts. Once you inline a template variables may be accessed in each templates, that is fairly useful as a result of you do not have to repeat the identical code many times, however you need to use variables and reuse chunks of Leaf code in a clear and environment friendly manner. Let me present you ways this works.

It is usually doable to make use of the coalescing operator to supply fallback values for nil variables.




Outline, Consider, Inline

One of many largest debate in Leaf is the entire template hierarchy system. In Tau, all the strategy 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 methodology actually places the content material of a template into one other. You’ll be able to even use uncooked values should you do not wish to carry out different operations (corresponding 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("residence", as: uncooked)
    </physique>
</html>

<!-- residence.leaf -->
<h1>Hey Leaf Tau!</h1>

As you possibly can see we’re merely placing the content material of the house template into the physique part of the index template.

Now it is extra attention-grabbing once we skip the uncooked half and we inline an everyday template that incorporates different expressions. We’re going to flip issues just a bit bit and render the house template as a substitute of the index.


app.get() { req -> EventLoopFuture<View> in
    req.leaf.render(template: "residence", 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 will attempt 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>

<!-- residence.leaf -->
<h1>Hey Leaf Tau!</h1>
#inline("index")


Wait a minute… this code is just not going to work. Within the residence template first we print the physique variable, then we inline the index template and print its contents. That is not what we wish. I wish to use the contents of the house template and place it in between the physique tags. 💪





Consider

Meet consider, a perform that may consider a Leaf definition. You’ll be able to consider this as a block variable definition in Swift. You’ll be able to create a variable with a given title and in a while name that variable (consider) utilizing parentheses after the title of the variable. Now you are able to do the identical skinny in Leaf by utilizing the consider key phrase or instantly calling the block like a perform.


<!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 need to use the `#bodyBlock()` syntax #)
    </physique>
</html>


On this template we will consider the bodyBlock and in a while we’ll be capable of outline it elsewhere.




Outline

Definitions. Lastly arrived to the final element that we’ll must compose templates. Now we will create our physique block within the residence template.


#outline(bodyBlock):
<h1>#(physique)</h1>
#enddefine

#inline("index")

Now should you reload the browser (Leaf cache have to be disabled) every thing 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 will consider it in a while. We merely print out the physique context variable inside this block, the physique variable is a context variable coming from Swift, that is fairly simple. Subsequent we inline the index template (think about copy-pasting total content material of the index template into the house template) which is able to print out the title context variable and evaluates the bodyBlock. The bodyBlock shall be out there since we have simply outlined it earlier than our inline assertion. Straightforward peasy. 😝


<!-- var, let -->
#var(x = 10)
#let(foo = "bar")

<!-- outline -->
#outline(resultBlock = x + 1)
#outline(bodyBlock):
    <h2>Hey, world!</h2>
    <p>I am a multi-line block definition</p>
#endblock

<!-- consider -->
#consider(resultBlock)
#bodyBlock()


I am actually joyful about these adjustments, as a result of Leaf is heading into the correct course, and people individuals who haven’t used the pre-released Leaf 4 variations but these adjustments will not trigger that a lot hassle. This new strategy follows extra like the unique Leaf 3 conduct.



Goodbye tags. Hey entities!

Nothing is a tag anymore, however they’re separated to the next issues:

  • Blocks (e.g. #for, #whereas, #if, #elseif, #else)
  • Features (e.g. #Date, #Timestamp, and so forth.)
  • Strategies (e.g. .depend(), .isEmpty, and so forth.)

Now you can create your very personal features, strategies and even blocks. 🔥

public struct Hey: LeafFunction, StringReturn, Invariant {
    public static var callSignature: [LeafCallParameter] { [.string] }

    public func consider(_ params: LeafCallValues) -> LeafData {
        guard let title = params[0].string else {
            return .error("`Hey` have to be referred to as with a string parameter.")
        }
        return .string("Hey (title)!")
    }
}

public func configure(_ app: Utility) throws {

    LeafConfiguration.entities.use(Hey(), asFunction: "Hey")
    
}

Now you need to use this perform in your templates like this:

#Hey("Leaf Tau")

You’ll be able to occasion overload the identical perform 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("`Hey` have to be referred to as with a string parameter.")
        }
        let prefix = params[1].string!
        return .string("(prefix) (title)!")
    }
}

public func configure(_ app: Utility) throws {


    LeafConfiguration.entities.use(Hey(), asFunction: "Hey")
    LeafConfiguration.entities.use(HelloPrefix(), asFunction: "Hey")

    
}

This manner you need to use a number of variations of the identical performance.

#Hey("Leaf Tau")
#Hey(title: "Leaf Tau", prefix: "Hello")

Here is one other instance of a customized Leaf methodology:


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: Utility) throws {

    LeafConfiguration.entities.use(DropLast(), asMethod: "dropLast")
    
}

You’ll be able to outline your individual Leaf entities (extensions) through protocols. You do not have to recollect all of them, as a result of there’s numerous them, however that is the sample that it’s best to search for Leaf*[Method|Function|Block] for the return sorts: [type]Return. If you do not know invariant is a perform that produces the identical output for a given enter and it has no unwanted side effects.

You’ll be able to register these entities as[Function|Method|Block] by the entities property. It will take some time till you get aware of them, however luckily Leaf 4 comes with fairly a great 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: Utility) throws {

    LeafConfiguration.entities.use(Path(), asFunction: "Path")

    
}

Oh, I virtually forgot to say that should you want particular entry to the app or req property it’s important to outline an unsafe entity, which shall be thought of as a nasty follow, however luckily now we have one thing else to interchange the necessity for accessing this stuff…



Scopes

If you should 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 Utility {
    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 {
            attempt req.leaf.context.register(turbines: req.customLeafVars, toScope: "req")
            attempt req.leaf.context.register(turbines: req.utility.customLeafVars, toScope: "app")
        }
        catch {
            return req.eventLoop.makeFailedFuture(error)
        }
        return subsequent.reply(to: req)
    }
}

public func configure(_ app: Utility) throws {

    app.middleware.use(ScopeExtensionMiddleware())

    
}

Lengthy story quick, you possibly can put LeafData values right into a customized scope, the good factor about this strategy is that they are often lazy, so Leaf will solely compute the corresponding values if when are getting used. The query is, how can 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>

It’s best 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: Utility) 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")
        attempt context.register(object: versionInfo, toScope: "api")
        return req.leaf.render(template: "residence", 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")
attempt context.register(object: versionInfo, toScope: "api")
attempt context.register(turbines: versionInfo.extendedVariables, toScope: "api")
return req.leaf.render(template: "residence", context: context)


There may be an app and req scope out there by default, so you possibly can prolong these by an extension that may return a [String: LeafDataGenerator] variable.




Abstract

As you possibly can 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 enable you to through the migration course of, and I imagine 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 constructions, Leaf variables and the redesigned hierarchy system will help us to design much more highly effective reusable templates. By means of entity and the scope API we can carry Leaf to a totally new stage. 🍃



Leave a Reply