Kitura-TemplateEngine
The Kitura template engine abstraction layer.
Kitura-TemplateEngine provides a TemplateEngine
protocol to unify the APIs of multiple template engines and integrate them with Kitura’s content generation APIs. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. This approach makes it easier to design an HTML page with integrated Swift code.
List of Plugins:
Kitura-TemplateEngine is an easy to learn, consumable framework that comes with a set of implemented plugins:
Usage
We don’t expect you to need to import Kitura-TemplateEngine, as it will automatically be pulled in as a dependency by the above plugins (you can see an example of this in Examples below) - unless you are implementing a new plugin for Kitura-TemplateEngine. If you do need to directly add Kitura-TemplateEngine as a dependency you can do so as follows:
Add dependencies
Add the Kitura-TemplateEngine
package to the dependencies within your application’s Package.swift
file. Substitute "x.x.x"
with the latest Kitura-TemplateEngine
release.
.package(url: "https://github.com/Kitura/Kitura-TemplateEngine.git", from: "x.x.x")
Add KituraTemplateEngine
to your target’s dependencies:
.target(name: "example", dependencies: ["KituraTemplateEngine"]),
Import package
import KituraTemplateEngine
Examples
The following code examples use the Kitura-StencilTemplateEngine, however, because this is an abstraction layer, Stencil could be substituted for any supported template engine.
If you are using Stencil, within your Package.swift
file you will need to:
- Define “https://github.com/Kitura/Kitura-StencilTemplateEngine.git” as a dependency.
- Add “KituraStencil” to the targets for Application.
You will also need to add KituraStencil
to the file where you’re writing your Swift code:
import KituraStencil
The following code initializes a Stencil template engine and adds it to the Kitura router.
This will render files with the template engine’s default file extension, in this example these would be .stencil
files.
router.add(templateEngine: StencilTemplateEngine())
Here we show how to render files which don’t have the same default file extension as the chosen template engine. In this example useDefaultFileExtension
is set to false, so the default file extension (.stencil
in this case) will not be rendered and files with the extension .example
will be rendered.
router.add(templateEngine: StencilTemplateEngine(), forFileExtensions: [".example"], useDefaultFileExtension: false)
If there are any files with file extensions which do not match any of the template engines which have been added to the router, the router will render the file using the default template engine. You can set the default template engine for the router as follows:
router.setDefault(templateEngine: StencilTemplateEngine())
The following example will render the Stencil template example.stencil
and add it to our router’s response. The template file will be retrieved from the default location, which is the Views
folder. The context variable allows you to pass data through to the template engine and must be valid JSON.
router.get("/example") { request, response, next in
var context: [String: Any] = ["key" : "value"]
try response.render("example.stencil", context: context)
next()
}
API Documentation
For more information visit our API reference.
Community
We love to talk server-side Swift, and Kitura. Join our Slack to meet the team!
License
This library is licensed under Apache 2.0. Full license text is available in LICENSE.