# 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)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://iris-go.gitbook.io/iris/view-templates/view.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.