# Documentation

Iris supports 7 template engines out-of-the-box, developers can still use any external golang template engine, as `Context.ResponseWriter()` is an `io.Writer`.

All template engines share a common API i.e. Parse using embedded assets, Layouts and Party-specific layout, Template Funcs, Partial Render and more.

| # | Name       | Parser                                                  |
| - | ---------- | ------------------------------------------------------- |
| 1 | HTML       | [html/template](https://pkg.go.dev/html/template)       |
| 2 | Blocks     | [kataras/blocks](https://github.com/kataras/blocks)     |
| 3 | Django     | [flosch/pongo2](https://github.com/flosch/pongo2)       |
| 4 | Pug        | [Joker/jade](https://github.com/Joker/jade)             |
| 5 | Handlebars | [aymerick/raymond](https://github.com/aymerick/raymond) |
| 6 | Jet        | [CloudyKit/jet](https://github.com/CloudyKit/jet)       |
| 7 | Ace        | [yosssi/ace](https://github.com/yosssi/ace)             |

[List of Examples](https://github.com/kataras/iris/tree/main/_examples/view).

A view engine can be registered per-Party. To **register** a view engine use the `Application/Party.RegisterView(ViewEngine)` method as shown below.

Load all templates from the "./views" folder where extension is ".html" and parse them using the standard `html/template` package.

```go
// [app := iris.New...]
tmpl := iris.HTML("./views", ".html")
app.RegisterView(tmpl)
```

## Render

To **render** or execute a view use the `Context.View` method inside the main route's handler. E.g. to load the `./views/hi.html` template file:

```go
ctx.View("hi") // or hi.html
```

## Pass Data

To **bind** Go values with key-value pattern inside a view through middleware or main handler use the `Context.ViewData` method before the `Context.View` one.

Bind: `{{.message}}` with `"Hello world!"`.

```go
ctx.ViewData("message", "Hello world!")
```

To bind a Go **model** to a view you have two options:

**1.**

```go
ctx.ViewData("user", User{})

// variable binding as {{.user.Name}}
```

**2.**

```go
ctx.View("user-page.html", User{})

// root binding as {{.Name}}
```

To **add a template function** use the `AddFunc` method of the preferred view engine.

```go
//       func name, input arguments, render value
tmpl.AddFunc("greet", func(s string) string {
    return "Greetings " + s + "!"
})
```

To **reload on each request** set the view engine's `Reload` method.

```go
tmpl.Reload(true)
```

## Embedded

To use **embedded** templates and not depend on local file system use the [go-bindata](https://github.com/go-bindata/go-bindata) external tool and pass its `Asset` and `AssetNames` functions to the `Binary` method of the preferred view engine.

```go
tmpl.Binary(Asset, AssetNames)
```

Example Code:

Please read the *comments* too.

```go
// file: main.go
package main

import "github.com/kataras/iris/v12"

func main() {
    app := iris.New()

    // Parse all templates from the "./views" folder
    // where extension is ".html" and parse them
    // using the standard `html/template` package.
    tmpl := iris.HTML("./views", ".html")

    // Enable re-build on local template files changes.
    tmpl.Reload(true)

    // Default template funcs are:
    //
    // - {{ urlpath "myNamedRoute" "pathParameter_ifNeeded" }}
    // - {{ render "header.html" }}
    // and partial relative path to current page:
    // - {{ render_r "header.html" }} 
    // - {{ yield }}
    // - {{ current }}
    // Register a custom template func:
    tmpl.AddFunc("greet", func(s string) string {
        return "Greetings " + s + "!"
    })

    // Register the view engine to the views,
    // this will load the templates.
    app.RegisterView(tmpl)

    // Method:    GET
    // Resource:  http://localhost:8080
    app.Get("/", func(ctx iris.Context) {
        // Bind: {{.message}} with "Hello world!"
        ctx.ViewData("message", "Hello world!")
        // Render template file: ./views/hi.html
        ctx.View("hi.html")
    })

    app.Listen(":8080")
}
```

```html
<!-- file: ./views/hi.html -->
<html>
<head>
    <title>Hi Page</title>
</head>
<body>
    <h1>{{.message}}</h1>
    <strong>{{greet "to you"}}</strong>
</body>
</html>
```

Open a browser tab at <http://localhost:8080>.

The **rendered result** will look like this:

```html
<html>
<head>
    <title>Hi Page</title>
</head>
<body>
    <h1>Hello world!</h1>
    <strong>Greetings to you!</strong>
</body>
</html>
```

## Multitemplate

Iris allows unlimited number of registered view engines per Application. Besides that, you can register a view engine **per Party or through middleware too!**.

```go
// Register a view engine per group of routes.
adminGroup := app.Party("/admin")
adminGroup.RegisterView(iris.Blocks("./views/admin", ".html"))
```

### Through Middleware

```go
func middleware(views iris.ViewEngine) iris.Handler {
	return func(ctx iris.Context) {
		ctx.ViewEngine(views)
		ctx.Next()
	}
}
```

**Usage**

```go
// Register a view engine on-fly for the current chain of handlers.
views := iris.Blocks("./views/on-fly", ".html")
views.Load()

app.Get("/", setViews(views), onFly)
```