<commit_before>---
### TRANSLATION INSTRUCTIONS FOR THIS SECTION:
### TRANSLATE THE VALUE OF THE title ATTRIBUTE AND UPDATE THE VALUE OF THE lang ATTRIBUTE. 
### DO NOT CHANGE ANY OTHER TEXT. 
layout: page
title: Templating
menu: resources
lang: en
redirect_from: "/resources/tutorial-todo.html"
### END HEADER BLOCK - BEGIN GENERAL TRANSLATION
---

Kitura is a lightweight, modular framework &mdash; this means that by default you get only basic HTTP functionality, like routing, parameter handling, parsing request body, etc. You can augment Kitura's out-of-the-box functionality by adding additional packages to your `Package.swift` file. 

A [template engine](https://en.wikipedia.org/wiki/Template_processor) allows _rendering_ of documents using static templates by substituting template variables with actual values at runtime. This page explains how you can use template engines integrated with Kitura in your Kitura apps.

# Kitura template engines
Kitura template engines are classes that implement the _TemplateEngine_ protocol from the [Kitura-TemplateEngine package](https://github.com/IBM-Swift/Kitura-TemplateEngine/blob/master/Sources/KituraTemplateEngine/TemplateEngine.swift). Currently, two Kitura template engines are supported:

1. [Kitura-MustacheTemplateEngine](https://github.com/IBM-Swift/Kitura-MustacheTemplateEngine)
2. [Kitura-StencilTemplateEngine](https://github.com/IBM-Swift/Kitura-StencilTemplateEngine).

##### Note! As of September 2016 GRMustache is available on macOS only and has not been fully ported to Swift 3.0. Please follow the [Kitura-MustacheTemplateEngine](https://github.com/IBM-Swift/Kitura-MustacheTemplateEngine) community for more information.

You can provide your own Kitura template engine by implementing the _TemplateEngine_ protocol from [Kitura-TemplateEngine package](https://github.com/IBM-Swift/Kitura-TemplateEngine/blob/master/Sources/KituraTemplateEngine/TemplateEngine.swift).

 
# Adding a template engine to your Kitura app 
To use a template engine you need to specify a dependency in `Package.swift` for the engine you want to use. You can specify multiple dependencies if you wish to support more than one template engine (e.g. both Mustache and Stencil). In our example we'll add both templates to demonstrate GRMustache and Stencil integration.

```swift
import PackageDescription

let package = Package(
    name: "myTemplates",
    dependencies: [
        .Package(url: "https://github.com/IBM-Swift/Kitura.git", majorVersion: 1, minor: 0),
        .Package(url: "https://github.com/IBM-Swift/Kitura-MustacheTemplateEngine.git", majorVersion: 1, minor: 0),
        .Package(url: "https://github.com/IBM-Swift/Kitura-StencilTemplateEngine.git", majorVersion: 1, minor: 0)
 ])
```

>Tip: If you generated your Xcode project previously, you have to [regenerate](http://www.kitura.io/en/starter/xcode.html) it once you add a new dependency so Xcode will be aware of the added dependency.


# Adding your template files to your Kitura app
Template files are text files that follow the syntax of a template engine. Here is an example of a Mustache template, taken from [GRMustache.swift](https://github.com/groue/GRMustache.swift) and a Stencil template, taken from [Stencil](https://github.com/kylef/Stencil/blob/master/README.md).

`document.mustache`:

```
Hello {{name}}
Your beard trimmer will arrive on {{format(date)}}.
{{#late}}
Well, on {{format(realDate)}} because of a Martian attack.
{{/late}}
```

`document.stencil`

```
There are {{ articles.count }} articles.

{% for article in articles %}
  - {{ article.title }} by {{ article.author }}.
{% endfor %}
```

Template files should be placed in a _Views directory_ which should be known to _Kitura Router_. By default, _Kitura Router_ gets the template files from the `./Views/` directory in the directory where `Kitura` runs. You can change the _Views directory_ per [Router](https://github.com/IBM-Swift/Kitura/blob/master/Sources/Kitura/Router.swift) instance by setting `Router.viewsPath` variable.

```
/myTemplateApp
|
|--/Sources
  |-- main.swift
|--/Views
  |-- document.mustache
  |-- document.stencil
```

# Registering a template engine with a Router instance
You should import the package of the template engine:

```swift
import KituraMustache
import KituraStencil
```

To use the template engine, you must register it with a Router instance. This is done by calling the  `Router.add(templateEngine:)` function, e.g.:

```swift
let router = Router()
router.add(templateEngine: MustacheTemplateEngine())
router.add(templateEngine: StencilTemplateEngine())
```

# Rendering a template
You can render a template by calling the `response.render(_:context)` function. Example code for the `document.mustache` and `document.stencil` template files:

```swift
// Handle HTTP GET requests to GRMustache/
router.get("/delivery") { request, response, next in
    defer {
        next()
    }

    // the example from https://github.com/groue/GRMustache.swift/blob/master/README.md
    var context: [String: Any] = [
        "name": "Arthur",
        "date": Date(),
        "realDate": Date().addingTimeInterval(60*60*24*3),
        "late": true
    ]

    // Let template format dates with ``
    let dateFormatter = DateFormatter()
    dateFormatter.dateStyle = .medium<commit_msg>Update templating.md<commit_after>---
### TRANSLATION INSTRUCTIONS FOR THIS SECTION:
### TRANSLATE THE VALUE OF THE title ATTRIBUTE AND UPDATE THE VALUE OF THE lang ATTRIBUTE. 
### DO NOT CHANGE ANY OTHER TEXT. 
layout: page
title: Templating
menu: resources
lang: en
redirect_from: "/resources/tutorial-todo.html"
### END HEADER BLOCK - BEGIN GENERAL TRANSLATION
---

Kitura is a lightweight, modular framework &mdash; this means that by default you get only basic HTTP functionality, like routing, parameter handling, parsing request body, etc. You can augment Kitura's out-of-the-box functionality by adding additional packages to your `Package.swift` file. 

A [template engine](https://en.wikipedia.org/wiki/Template_processor) allows _rendering_ of documents using static templates by substituting template variables with actual values at runtime. This page explains how you can use template engines integrated with Kitura in your Kitura apps.

# Kitura template engines
Kitura template engines are classes that implement the _TemplateEngine_ protocol from the [Kitura-TemplateEngine package](https://github.com/IBM-Swift/Kitura-TemplateEngine/blob/master/Sources/KituraTemplateEngine/TemplateEngine.swift). Currently, two Kitura template engines are supported:

1. [Kitura-MustacheTemplateEngine](https://github.com/IBM-Swift/Kitura-MustacheTemplateEngine)
2. [Kitura-StencilTemplateEngine](https://github.com/IBM-Swift/Kitura-StencilTemplateEngine).

##### Note! As of September 2016 GRMustache is available on macOS only and has not been fully ported to Swift 3.0. Please follow the [Kitura-MustacheTemplateEngine](https://github.com/IBM-Swift/Kitura-MustacheTemplateEngine) community for more information.

You can provide your own Kitura template engine by implementing the _TemplateEngine_ protocol from [Kitura-TemplateEngine package](https://github.com/IBM-Swift/Kitura-TemplateEngine/blob/master/Sources/KituraTemplateEngine/TemplateEngine.swift).

 
# Adding a template engine to your Kitura app 
To use a template engine you need to specify a dependency in `Package.swift` for the engine you want to use. You can specify multiple dependencies if you wish to support more than one template engine (e.g. both Mustache and Stencil). In our example we'll add both templates to demonstrate GRMustache and Stencil integration.

```swift
import PackageDescription

let package = Package(
    name: "myTemplates",
    dependencies: [
        .Package(url: "https://github.com/IBM-Swift/Kitura.git", majorVersion: 1, minor: 0),
        .Package(url: "https://github.com/IBM-Swift/Kitura-MustacheTemplateEngine.git", majorVersion: 1, minor: 0),
        .Package(url: "https://github.com/IBM-Swift/Kitura-StencilTemplateEngine.git", majorVersion: 1, minor: 0)
 ])
```

>Tip: If you generated your Xcode project previously, you have to [regenerate](http://www.kitura.io/en/starter/xcode.html) it once you add a new dependency so Xcode will be aware of the added dependency.


# Adding your template files to your Kitura app
Template files are text files that follow the syntax of a template engine. Here is an example of a Mustache template, taken from [GRMustache.swift](https://github.com/groue/GRMustache.swift) and a Stencil template, taken from [Stencil](https://github.com/kylef/Stencil/blob/master/README.md).

`document.mustache`:

```
Hello {{name}}
Your beard trimmer will arrive on {{format(date)}}.
{{#late}}
Well, on {{format(realDate)}} because of a Martian attack.
{{/late}}
```

`document.stencil`

```
There are {{ articles.count }} articles.

{% for article in articles %}
  - {{ article.title }} by {{ article.author }}.
{% endfor %}
```

Template files should be placed in a _Views directory_ which should be known to _Kitura Router_. By default, _Kitura Router_ gets the template files from the `./Views/` directory in the directory where `Kitura` runs. You can change the _Views directory_ per [Router](https://github.com/IBM-Swift/Kitura/blob/master/Sources/Kitura/Router.swift) instance by setting `Router.viewsPath` variable.

```
/myTemplateApp
|
|--/Sources
  |-- main.swift
|--/Views
  |-- document.mustache
  |-- document.stencil
```

# Registering a template engine with a Router instance
You should import the package of the template engine:

```swift
import KituraMustache
import KituraStencil
```

To use the template engine, you must register it with a Router instance. This is done by calling the  `Router.add(templateEngine:)` function, e.g.:

```swift
let router = Router()
router.add(templateEngine: MustacheTemplateEngine())
router.add(templateEngine: StencilTemplateEngine())
```

# Rendering a template
You can render a template by calling the `response.render(_:context)` function. Here's the the code for the `document.mustache` and `document.stencil` template files we referenced earlier:

```swift
// Handle HTTP GET requests to GRMustache/
router.get("/delivery") { request, response, next in
    defer {
        next()
    }

    // the example from https://github.com/groue/GRMustache.swift/blob/master/README.md
    var context: [String: Any] = [
        "name": "Arthur",
        "date": Date(),
        "realDate": Date().addingTimeInterval(60*60*24*3),
        "late": true
    ]

    // Let template format dates with ``
    let dateFormatter = DateFormatter()
    dateFormatter.dateStyle = .medium
{'fraction_non_alphanumeric': 0.10472086923941551, 'fraction_numerical': 0.003934057699512926, 'mean_word_length': 4.49794026776519, 'pattern_counts': {'":': 8, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 26, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5883020', 'n_tokens_mistral': 3127, 'n_tokens_neox': 2925, 'n_words': 1095}