Perfect-Mustache

Mustache template support for Perfect.

This package is designed to work along with Perfect. It provides Mustache template support for your server.

Quick Start

To start, add this project as a dependency in your Package.swift file.

.package(url: "https://github.com/PerfectlySoft/Perfect-Mustache.git", from: "3.0.0")

Then, add "PerfectMustache" to the list of dependencies for the target that will use PerfectMustache.

Example target configuration:

targets: [.target(name: "PerfectTemplate", dependencies: ["PerfectHTTPServer", "PerfectMustache"])]

Basic usage:

let map: [String:Any] = ["fullName":fullName, "uri":uri, "authToken":authToken]
let ctx = MustacheEvaluationContext(templatePath: emailTemplate, map: map)
let result = try ctx.formulateResponse(withCollector: MustacheEvaluationOutputCollector())

The following snippet illustrates how to use mustache templates in your URL handler. In this example, the template named "test.html" would be located in your server's web root directory.

{
	request, response in 
	let webRoot = request.documentRoot
	mustacheRequest(request: request, response: response, handler: TestHandler(), templatePath: webRoot + "/test.html")
}

The template page handler, which you would impliment, might look like the following.

struct TestHandler: MustachePageHandler { // all template handlers must inherit from PageHandler
	// This is the function which all handlers must impliment.
	// It is called by the system to allow the handler to return the set of values which will be used when populating the template.
	// - parameter context: The MustacheWebEvaluationContext which provides access to the HTTPRequest containing all the information pertaining to the request
	// - parameter collector: The MustacheEvaluationOutputCollector which can be used to adjust the template output. For example a `defaultEncodingFunc` could be installed to change how outgoing values are encoded.
	func extendValuesForResponse(context contxt: MustacheWebEvaluationContext, collector: MustacheEvaluationOutputCollector) {
		var values = MustacheEvaluationContext.MapType()
		values["value"] = "hello"
		/// etc.
		contxt.extendValues(with: values)
		do {
			try contxt.requestCompleted(withCollector: collector)
		} catch {
			let response = contxt.webResponse
			response.status = .internalServerError
			response.appendBody(string: "\(error)")
			response.completed()
		}
	}
}

Look at the UploadEnumerator example for a more concrete example.

Tag Support

This mustache template processor supports:

• {{regularTags}}
• {{{unencodedTags}}}
• {{& unescapedTags}}
• {{# sections}} ... {{/sections}}
• {{^ invertedSections}} ... {{/invertedSections}}
• {{! comments}}
• {{> partials}}
• lambdas

Partials

All files used for partials must be located in the same directory as the calling template. Additionally, all partial files must have the file extension of mustache but this extension must not be included in the partial tag itself. For example, to include the contents of the file foo.mustache you would use the tag {{> foo }}.

Encoding

By default, all encoded tags (i.e. regular tags) are HTML encoded and < & > entities will be escaped. In your handler you can manually set the MustacheEvaluationOutputCollector.defaultEncodingFunc function to perform whatever encoding you need. For example when outputting JSON data you would want to set this function to something like the following:

collector.defaultEncodingFunc = { 
	string in 
	return (try? string.jsonEncodedString()) ?? "bad string"
}

Lambdas

Functions can be added to the values dictionary. These will be executed and the results will be added to the template output. Such functions should have the following signature:

(tag: String, context: MustacheEvaluationContext) -> String

The tag parameter will be the tag name. For example the tag {{name}} would give you the value "name" for the tag parameter.

Further Documentation

For more information, please visit perfect.org.