Customized Leaf tags in Vapor 4

prolong Leaf?

With the rebirth of Leaf we are able to actually prolong the template engine and customized tags are only a factor of the previous. You realize in earlier variations of Leaf all the things was known as a tag and there was no differentiation between these little bastards beginning with the # image. Now issues have modified. There are various completely different entities in Leaf Tau.

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

This can be a great point and on high of this you possibly can create your very personal features, strategies and even blocks. This brings us to a totally extensible template engine that may render all the things in a non-blocking asynchronous means. How cool is that? 😎

Did I point out that Leaf you possibly can prolong the context with customized LeafDataGenerators? Sure, that is a factor now, prior to now you can use the userInfo object to set a “world” out there variable in Leaf, that was properly out there in each single template file.

Now there are some particular variables out there that you could prolong:

The present context in fact is what you go to your template utilizing the render technique written in Swift. It’s value to say that self is simply an alias to the present $context, so it does not issues which one you utilize. The $app and $req scopes are empty by design, however you possibly can prolong them. You’ll be able to even register your individual scope for instance $api and set all the things you want globally beneath that variable. I am going to present you ways to do that in a while.

As you possibly can see there are many choices out there to increase Leaf. It’s a must to suppose twice which path you’re taking, however it’s nice that we’ve got this many alternatives. Now we’ll stroll by of every of these items and I am going to present you write customized extensions for Leaf Tau. 🥳

prolong Leaf contexts?

One of the simple means of extending Leaf is to offer customized context variables. We are able to simply write an extension for the Software and the Request object and return LeafDataGenerator values with particular keys and in a while we are able to register these as further context variables.

import Vapor
import Leaf

extension Software {
    var customLeafVars: [String: LeafDataGenerator] {
        [
            "isDebug": .lazy(LeafData.bool(!self.environment.isRelease && self.environment != .production))
        ]
    }
}

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)
                    ]),
        ]
    }
}

A LeafDataGenerator object may be lazy or rapid. Speedy values might be saved immediately, alternatively lazy values will produce generator blocks which are going to be known as solely when the renderer wants them. Nothing particular, this works just like the lazy key phrase in Swift.

struct ScopeExtensionMiddleware: Middleware {

    func reply(to req: Request, chainingTo subsequent: Responder) -> EventLoopFuture<Response> {
        do {
            strive req.leaf.context.register(turbines: req.software.customLeafVars, toScope: "app")
            strive req.leaf.context.register(turbines: req.customLeafVars, toScope: "req")
        }
        catch {
            return req.eventLoop.future(error: error)
        }
        return subsequent.reply(to: req)
    }
}

We’d like an extension middleware that registers our generator variables to the given scope.

public func configure(_ app: Software) throws {

    app.middleware.use(ScopeExtensionMiddleware())

    
}

Attempt to print these values in a template file, you possibly can entry child-values utilizing the dot notation.

#(self)
#($context)

#($app)
#($app.isDebug)

#($req)
#($req.url)
#($req.url.host)
#($req.url.isSecure)
#($req.url.path)
#($req.url.port)
#($req.url.question)

Now we’re going to create a customized context to get some details about the host machine.

ultimate class ServerLeafContextGenerator: LeafContextPublisher {

    var osName: String {
        #if os(macOS)
        return "macOS"
        #elseif os(Linux)
        return "Linux"
        #elseif os(Home windows)
        return "Home windows"
        #else
        return "Unknown"
        #endif
        
    }

    lazy var leafVariables: [String: LeafDataGenerator] = [
        "os": .lazy([
            "name": LeafData.string(self.osName),
            "version": LeafData.string(ProcessInfo.processInfo.operatingSystemVersionString),
        ]),
        "cpu-cores": .rapid(ProcessInfo.processInfo.processorCount),
        "reminiscence": .rapid(ProcessInfo.processInfo.physicalMemory),
    ]
}

We are able to merely put this line subsequent to the opposite two within the scope extension middleware.

strive req.leaf.context.register(turbines: ServerLeafContextGenerator().leafVariables, toScope: "server")

This fashion we are able to get some more information concerning the server in our Leaf templates by utilizing the $server scope. One other means is to increase a scope regionally with a generator.

app.get("server-info") { req -> EventLoopFuture<View> in
    var context: LeafRenderer.Context = [
        "title": "Server info",
    ]
    strive context.register(object: ServerLeafContextGenerator(), toScope: "server")
    return req.leaf.render(template: "server-info", context: context)
}

The distinction is that within the second case the server scope is simply out there for a single endpoint, but when we register it by the middleware then it may be reached globally in each single Leaf file.

I feel scopes are very helpful, particularly Request associated ones. Previously we needed to create a customized Leaf tag to get the trail, however now we are able to use a scope extension and this data might be out there in all places. With the lazy load we additionally get some free efficiency enhancements.

Customized Leaf features and strategies

You’ll be able to create customized features and strategies for Leaf, I might say that this new API is the replacemenet of the outdated tag system. There are some variations and at first sight you would possibly suppose that it is tougher to create a operate with the brand new instruments, however in time you may get used to it.

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

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

This can be a very fundamental operate. Each single operate has a name signature, which is only a record of type-safe arguments. Features can have return sorts, thankfully there are pre-made protocols for these, so you do not have to implement the required stuff, however you possibly can say that this features is e.g. a StringReturn operate. Invariant signifies that the operate will all the time return the identical output for a similar enter. That is what you need more often than not, it additionally lets you keep away from side-effects.

Within the consider operate you may get entry to all of the enter parameters and you need to return with a LeafData sort. If a parameter is lacking or it might probably’t be casted to the right sort you possibly can all the time return with an error. Consider is wish to the outdated render technique, however it’s far more superior.

LeafConfiguration.entities.use(Hi there(), asFunction: "Hi there")

You additionally must register this newly created operate beneath a give title.

#Hi there("Leaf Tau")

Oh by the way in which strategies are simply particular features so you possibly can construct them the identical means and register them by way of the asMethod: property. If you wish to see extra examples, it’s best to check out my different submit about what’s new in Leaf Tau or scroll all the way down to the final part of this text.

construct customized Leaf blocks?

This can be a very attention-grabbing and sophisticated subject. Blocks are particular form of LeafFunctions, identical to strategies, however issues are just a bit bit extra difficult on this case. Instance time:

import Vapor
import Leaf


struct MaybeBlock: LeafBlock, VoidReturn, Invariant {
    
    static var parseSignatures: ParseSignatures? = nil
    static var evaluable: Bool = false
    var scopeVariables: [String]? = nil

    static var callSignature: [LeafCallParameter] { [.double(labeled: "chance")] }
         
    static func instantiate(_ signature: String?, _ params: [String]) throws -> MaybeBlock { .init() }

    mutating func evaluateScope(_ params: LeafCallValues, _ variables: inout [String: LeafData]) -> EvalCount {
        params[0].double! > Double.random(in: 0..<1) ? .as soon as : .discard
    }
    
    mutating func reEvaluateScope(_ variables: inout [String : LeafData]) -> EvalCount {
        fatalError("Error: `Possibly` blocks cannot be re-evaluated.")
    }
}

This block has a name signature with a labeled argument known as probability. It has an instantiate technique which is utilized by the Leaf engine to create this block. It will not have any parseSignatures or scope variables, we’ll depart that for the for block (go and verify the supply in LeafKit if you’re curious & courageous sufficient). We set evaluable to false since we do not wish to make it callable by way of the #consider operate. Now let’s discuss scope analysis actual fast.

The evaluateScope technique might be known as first when the block inside your template will get evaluated. It’s a must to return an EvalCount on this technique, which can resolve what number of instances ought to we print out the contents in between your block (#[name]:THIS PART#finish[name]).

Mainly when a LeafBlock is evaluated the primary time, it is by way of evaluateScope. If that returns a consequence somewhat than nil, any additional calls will use reEvaluateScope as a substitute. – tdotclare

If EvalCount is about to discard then the contents might be discarded, in any other case it will be evaluated as many instances as you come back. If the rely is .as soon as which means the tip of the story, but when it get’s evaluated a number of instances and you do not want further params for additional analysis, then the reEvaluateScope might be known as for all the opposite cycles.

LeafConfiguration.entities.use(MaybeBlock.self, asBlock: "possibly")

Remember that we’ve got to register this block with a given title earlier than we might use it.

#possibly(probability: 0.5):
    <p>Is that this going to occur? 50-50.</p>
#endmaybe

That is it, we have simply prolonged Leaf with a fundamental block, you possibly can attempt to construct your individual A/B testing Chained block if you wish to dig deeper, however that is fairly a complicated subject and there are not any docs out there simply but so you have got to try the LeafKit supply information in a lot of the circumstances.

Helpful Leaf extensions.

I’ve made a bunch of helpful Leaf extensions out there beneath the LeafFoundation repository. It is a work-in-progress challenge, however hopefully it will comprise lot extra attention-grabbing extensions by the point Leaf 4 might be formally launched. PR’s are welcomed. 😬