LeafConfiguration Formatting Options

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.

Property Options

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

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

File Sandboxing, Directory Limiting, and Multiple Template Sources

This patch was authored and released by @tdotclare.

LeafSources, LeafSource and File Sandboxing/Limiting in NIOLeafFiles

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 from
• LeafSource (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 behavior

For more details, please refer to the associated LeafKit update:
LeafKit 1.0.0rc-1.11: LeafSources, LeafSource and File Sandboxing/Limiting in NIOLeafFiles

BREAKING CHANGES FOR UNUSUAL USAGE CASES

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

NOTES

• 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.

Additional Changes

Updates Package.swift to require Vapor 4 release

Added userInfo context, config, test

This patch was authored by @tib and released by @tanner0101.

• Added the ability to config userInfo on app.leaf.
• The userInfo dictionary is now accessible for custom leaf tags
• See testContextUserInfo for more info

Tags config, files protocol, and context passing

This patch was authored and released by @tanner0101.

Adds 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.

Release Candidate 1

Updates to Swift 5.2.

Release candidates represent the final shift toward focusing on bug fixes and documentation. Breaking changes will only be accepted for critical issues. We expect a final release of this package shortly after Swift 5.2's release date.

Make app.leaf.cache settable

LeafCache is now settable (#155, fixes #154).

app.leaf.cache.isEnabled = false

This patch was authored and released by @tanner0101.

Allow Optional values when encoding

Removes force unwrapping in the LeafEncoder allowing for types to be Optional.

This patch was authored by @namolnad and released by @loganwright.

Beta 3 Update

This patch was authored and released by @gwynne.

• Update to match new Vapor requirements for OS
• Require current Vapor beta version
• Leaf's major beta version has been bumped due to the new OS requirement (a breaking change), even though there are no changes to Leaf itself

Leaf 4.0.0 Beta 2

• Updated to latest LeafKit and Vapor beta 2 releases (#149)

Configuration changes:

import Leaf
import Vapor

// beta.1
app.use(LeafProvider())

// beta.2
app.views.use(.leaf)

Rendering changes:

// beta.2
app.get("test-file") { req in
    req.view.render(#file, ["foo": "bar"])
}

Leaf 4.0.0 Beta 1

Merge pull request #144 from vapor/tn-beta-1

beta 1