🍃 An expressive, performant, and extensible templating language built for Swift.
Using arrays for top-level Contexts in Leaf is not support. This changes the behaviour of Leaf to throw an error instead of fatalErroring and taking down the app.
Resolves #190
Out of the box, the LeafRenderer offers a base API which can render
Leaf templates to a ByteBuffer. This requires the context to be provided
as a dictionary. With ViewRenderer conformance the LeafRenderer can
render View's using an Encodable context.
However, there's no middle ground: the LeafRenderer can't render
templates to a ByteBuffer using an Encodable context. Since
LeafEncoder is internal users can't make the extra hop from Encodable
context to dictionary to use the base API either. This functionality is helpful
when Leaf is used to render documents which aren't HTML.
As such this change adds an extension to LeafRenderer to render a
template to serialized bytes using an Encodable context.
Disable the cache in Leaf's renderer when the environment is set to development.
Resolves #185
Docs can be found at https://docs.vapor.codes/4.0/leaf/getting-started/
This release reverses the changes made by Tau. Tau became an awesomely complex and advanced renderer that outgrew Leaf's original view and Vapor. The core team made the decision to release Leaf in it's original form as something we could commit to maintaining and offer a simple HTML renderer. This means that Tau will be split out and offered as a separate renderer for those that want it and Tau won't be constrained by the requirements of the core team. If you want to keep using Tau we encourage you to do so! You can find it in the fork here. Note that the location may change in the future.
This release reflects the final API that will be tagged as 4.0.0 soon unless any glaring bugs come up.
tau is the final prerelease of LeafKit 1.0 and Leaf4.
This is a massive rebuild from the previous prerelease version and entirely replaces the architecture for extending the language; as such, there is no direct transition path for converting LeafTag objects to the new architecture directly.
Migration documents are coming soon to address how that functionality has improved and changed
If you currently use the Leaf4 pre-release versions, pin to the final
rcbranch in your Swift Package Manifest to avoid updating to this state if you are not ready to transition:dependencies: [ .package(url: "https://github.com/vapor/leaf-kit.git", .exact("1.0.0-rc.1.17")), .package(url: "https://github.com/vapor/leaf.git", .exact("4.0.0-rc.1.4")) ]
Leaf4 is a dynamic language templating engine for (and inspired by) Swift with a unique hybrid design to allow significant extensibility, customization, performance, and optimizations for a broad range of applications. Leaf templates function primarily as the View component of Model-View-Controller architectures.
As the successor to Leaf3, it greatly expands the language's capabilities and introduces significant changes that are oriented towards: simplfying integration of Leaf into applications; broader use beyond web-templating; robust handling of compiling templates; and improved, more powerful, and safer extensibility of templates at runtime.
LeafKit is the core architecture of Leaf4
Leaf is the bindings of LeafKit to Vapor and Vapor-specific configuration.
This release exposes configuration methods for setting the default presentation output of data in rendered Leaf templates.
Static options are settable only until app.leaf.renderer is accessed or a render(...) call is made.
Stored property options in a LeafConfiguration may be used in various ways by a LeafRenderer which the configuration object was for, and changes to them after the object was provided to a specific LeafRenderer will have no affect.
.rootDirectory: String // The default file directory used for file-system based `LeafSource`s
Static options on LeafConfiguration are effectively constant once any LeafRenderer has been instantiated and attempts to change them will assert in Debug and silently fail in Release to prevent inconsistent behavior.
// The global tag indicator for LeafKit
.tagIndicator: Character == "#"
// Encoding used when a template is serialized
.encoding: String.Encoding == .utf8
// Formatters for converting the base internal data types to Strings for serialization
.boolFormatter: (Bool) -> String = { $0.description } // Bool.description
.intFormatter: (Int) -> String = { $0.description } // Int.description
.doubleFormatter: (Double) -> String = { $0.description } // Double.description
.nilFormatter: () -> String = { "" } // Empty string (Optional containing .none)
.voidFormatter: () -> String = { "" } // Empty string (Tag with no return value)
.stringFormatter: (String) -> String = { $0 } // Identity return
.dataFormatter: (Data) -> String? =
{ String(data: $0, encoding: Self._encoding) } // Data using .encoding
// Note: Array & Dictionaries elements will already have been converted to Strings
.arrayFormatter: ([String]) -> String = // Array: [element, ..., element]
{ "[\($0.map {"\"\($0)\""}.joined(separator: ", "))]" }
.dictFormatter: ([String: String]) -> String = // Dictionary: [key: value, ..., key: value]
{ "[\($0.map { "\($0): \"\($1)\"" }.joined(separator: ", "))]" }
This update aligns Vapor+Leaf bindings to use LeafKit 1.0.0rc-1.11 API changes for sandboxing and file security behaviors, and using multiple sources for raw Leaf templates:
LeafSources stores multiple LeafSource*-adhering objects by name and maintains a default search order of which objects to attempt to read fromLeafSource (previously LeafFiles) represents any object with a directed behavior for interpreting a template name into its own reading space (eg, a filesystem or database)NIOLeafFiles gains initialization configuration for sandboxing and reading-limit behaviorFor more details, please refer to the associated LeafKit update: LeafKit 1.0.0rc-1.11: LeafSources, LeafSource and File Sandboxing/Limiting in NIOLeafFiles
If you are using a custom adherent to LeafFiles, you should update your object definition to conform to LeafSource and will no longer be able to access it via app.leaf.files. You will also need to expand "template" into a fully qualified file system path, if appropriate, internally - LeafRenderer will no longer directly expand the path before requesting it from a LeafSource
Adherents that wrapped NIOLeafFiles to use multiple directories may be better served by the new ability to have multiple LeafSource objects searched.
Please see above link to LeafKit
Default behavior for file access now limits all template references to prevent relative paths from escaping the configured ViewDirectory, and to block access to files without extensions, hidden files, or files in hidden directories.
These behaviors can be configured by setting Application.leaf.sources to LeafSources.singleSource(customNIOLeafFiles) where the NIOLeafFiles initializer takes custom settings (for example, to allow absolute/relative paths to escape to a configured higher level directory, or to block access to any file NOT ending in .leaf), and allows setting the default directory to attempt to read from.
Updates Package.swift to require Vapor 4 release
testContextUserInfo for more infoAdds new Leaf configuration options, including custom tags, to application.
app.leaf.tags["foo"] = FooTag()
app.leaf.files = TestFiles()
app.leaf.configuration.rootDirectory = "/"
Adds support for passing Request and Application to LeafKit's userInfo storage.
struct FooTag: LeafTag {
func render(_ context: LeafContext) throws -> LeafData {
context.request // Request?
context.application // Application?
...
}
}
These will be set automatically when using app.view or req.view.