Documentation
¶
Overview ¶
Package view registers a template engine so that Render, WithTemplate and Context.Render can render its templates. The engines live outside the framework: HTML, Django, Handlebars, Jet, Pug and Ace are in github.com/iris-contrib/views and Blocks is github.com/kataras/blocks. Any type that implements Engine can be registered.
Its entry point is Handler(engine), which returns a Handler that binds the engine to the requests that follow it. The engine itself is the single input, so it is a plain argument and there is no Options struct.
Index ¶
- Variables
- func AddFunc(ctx *context.Context, funcName string, fn any) bool
- func Data(ctx *context.Context, data any)
- func Ext(ctx *context.Context) string
- func GetData(ctx *context.Context) any
- func Handler(engine Engine) context.Handler
- func KeyValue(ctx *context.Context, key string, value any) error
- func Layout(ctx *context.Context, layout string)
- func Render(ctx *context.Context, templateName, layoutName string, data any) error
- func WithData(data any) context.Handler
- func WithFuncMap(funcMap template.FuncMap) context.Handler
- func WithLayout(layout string) context.Handler
- func WithTemplate(t *Template) context.Handler
- type Engine
- type EngineExtenser
- type EngineFuncer
- type ErrTemplateNotFound
- type Template
Constants ¶
This section is empty.
Variables ¶
var ErrNoEngine = errors.New("view engine is not available in the current context")
ErrNoEngine reports whether a view engine is not available in the current context. It's used when trying to render a view without a view engine.
Functions ¶
func AddFunc ¶
AddFunc adds a template function to the view engine that the request holds. It reports whether that engine takes functions, which means that it implements EngineFuncer.
The function is registered on the engine, so it is not per-request state:
- Every request and every route that uses the same engine can call it from then on.
- Do not pass a function that closes over ctx. It stays on the engine after the request has ended, while the Context it captured goes back to the pool and serves other requests. A value that belongs to one request goes into the view data (see Data and KeyValue), a function included: a template calls it with {{ call .Name arguments }}.
- When the function becomes callable depends on the engine. One that resolves function names while it parses, as html/template does, needs the function before it loads its templates, and an engine that is loaded at startup has done that before the first request arrives. For such an engine call its own AddFunc or Funcs method before Load.
Example:
rv := router.NewRoutePathReverser(app.RouterBuilder.Routes()) view.AddFunc(ctx, "urlpath", rv.Path)
func Ext ¶
Ext returns the final file extension (including the dot) which the view engine is responsible to render. It returns an empty string if the engine is not available in the current context.
func Handler ¶
Handler returns a context.Handler that stores the view engine to the context, by overriding any previous ones for the handler (chain).
func KeyValue ¶
KeyValue adds a key-value pair to the view data of the current request. The view data is created as a Map if it doesn't exist. If the view data is not a Map, it returns an error.
KeyValue never writes into a map that was given to Data or WithData, because WithData stores the same map on every request. The first call of a request copies such a map and writes to the copy, and the calls that follow reuse it. The map of the caller stays as it was, so read the result with GetData. The copy is shallow: a value that is itself a map or a slice is still shared.
func Render ¶
Render renders a template by its filename with an optional layout and data. It writes the response headers and body. It returns an error if the engine is not available in the current context. If the given "layoutName" is empty then it tries to get the layout from the context's view layout (see `Layout` function). If the given "data" is nil then it tries to get the data from the context's view data (see `Data` and `KeyValue` functions).
func WithData ¶
WithData returns a context.Handler that stores the view data to the context, by overriding any previous ones for the handler (chain).
Every request that passes through the handler gets the same value, so do not change it once the server runs. KeyValue does not: it copies a map before the first write of a request.
func WithFuncMap ¶
WithFuncMap returns a context.Handler that adds the given template.FuncMap to the view engine of the request, by calling AddFunc for each entry.
The functions are registered on the engine and not on the request, so read AddFunc before you use it. The handler adds the same functions again on every request, which only helps an engine that has not loaded its templates yet. To register functions once, call the engine's own method before its Load.
func WithLayout ¶
WithLayout returns a context.Handler that stores the view layout to the context, by overriding any previous ones for the handler (chain).
func WithTemplate ¶
WithTemplate returns a Handler that renders the given template.
Types ¶
type Engine ¶
type Engine interface {
// ExecuteTemplate should execute a template by its filename with an optional layout and data.
ExecuteTemplate(w io.Writer, templateName string, layoutName string, data any) error
}
Engine is the interface which all view engines should be implemented in order to be registered inside iris.
type EngineExtenser ¶
type EngineExtenser interface {
// Ext should return the final file extension (including the dot)
// which this view engine is responsible to render.
Ext() string
}
EngineExtenser is the interface which supports the retrieval of the template files extension.
type EngineFuncer ¶
type EngineFuncer interface {
// AddFunc should adds a function to the template's function map.
AddFunc(funcName string, funcBody any)
}
EngineFuncer is the interface which supports the registration of custom template functions.
type ErrTemplateNotFound ¶
ErrTemplateNotFound it's an error. It reports whether a template was not found in the parsed templates tree.
func (ErrTemplateNotFound) Error ¶
func (e ErrTemplateNotFound) Error() string
Error completes the `error` interface.
type Template ¶
type Template struct {
Code int `json:"code" yaml:"Code"`
Layout string `json:"layout" yaml:"Layout"`
Name string `json:"name" yaml:"Name"`
Data any `json:"data" yaml:"Data"`
// DataFunc can be used in order to return some `Data` based on the iris Context,
// from outside the context. E.g. when declaring the View outside of the handler scope.
//
// When DataFunc is not nil its result is rendered and the Data field is
// ignored. The result belongs to the request: Render does not store it in
// the Template, because WithTemplate gives the same Template to every
// request of a route.
DataFunc func(*context.Context) (any, error) `json:"-" yaml:"-"`
}
Template represents a view. It's used to render a view with a specific status code, layout and data. Usage:
ctx.Render(&Template{Name: "index.html", Layout: "layouts/main.html", Data: someData})