templates

Documentation

Overview

Package templates implements wrapper around html/template to provide lazy loading of templates and better integration with HTTP middleware framework.

Index

• func Get(c context.Context, name string) (*template.Template, error)
• func MustRender(c context.Context, out io.Writer, name string, args Args)
• func Render(c context.Context, name string, args Args) ([]byte, error)
• func Use(c context.Context, b *Bundle, e *Extra) context.Context
• func WithTemplates(b *Bundle) router.Middleware
• type Args
  • func MergeArgs(args ...Args) Args
• type Bundle
  • func (b *Bundle) EnsureLoaded(c context.Context) error
  • func (b *Bundle) Get(name string) (*template.Template, error)
  • func (b *Bundle) MustRender(c context.Context, e *Extra, out io.Writer, name string, args Args)
  • func (b *Bundle) Render(c context.Context, e *Extra, name string, args Args) ([]byte, error)
• type Extra
• type Loader
  • func AssetsLoader(assets map[string]string) Loader
  • func FileSystemLoader(fs fs.FS) Loader

Functions

func Get

func Get(c context.Context, name string) (*template.Template, error)

Get returns template from the currently loaded bundle or error if not found.

func MustRender

func MustRender(c context.Context, out io.Writer, name string, args Args)

MustRender renders the template into the output writer or panics.

It never writes partial output. It also panics if attempt to write to the output fails.

func Render

func Render(c context.Context, name string, args Args) ([]byte, error)

Render finds top level template with given name and calls its Execute or ExecuteTemplate method (depending on the value of Bundle.DefaultTemplate).

It always renders output into a byte buffer, to avoid partial results in case of errors.

func Use

func Use(c context.Context, b *Bundle, e *Extra) context.Context

Use replaces the template bundle in the context. There can be only one bundle installed at any time.

It also takes an Extra to be passed to bundle's DefaultArgs(...) callback when using Render(...) or MustRender(...) top-level functions.

DefaultArgs(...) can use the context and the given Extra to extract information about the environment.

func WithTemplates

func WithTemplates(b *Bundle) router.Middleware

WithTemplates is middleware that lazily loads template bundle and injects it into the context.

Wrapper reply with HTTP 500 if templates can not be loaded. Inner handler receives context with all templates successfully loaded.

Types

type Args

type Args map[string]any

Args contains data passed to the template.

func MergeArgs

func MergeArgs(args ...Args) Args

MergeArgs combines multiple Args instances into one. Returns nil if all passed args are empty.

type Bundle

type Bundle struct {
	// Loader will be called once to attempt to load templates on the first use.
	//
	// There are some predefined loaders you can use, see AssetsLoader(...)
	// for example.
	Loader Loader

	// DebugMode, if not nil, can return true to enable template reloading before
	// each use.
	//
	// It disables the caching of compiled templates, essentially. Useful during
	// development, where it can be set to luci/gae's info service
	// "IsDevAppServer" method directly.
	DebugMode func(context.Context) bool

	// FuncMap contains functions accessible from templates.
	//
	// Will be passed to Loader on first use. Not used after that.
	FuncMap template.FuncMap

	// DefaultTemplate is a name of subtemplate to pass to ExecuteTemplate when
	// rendering a template via Render(...) or MustRender(...).
	//
	// For example, if all templates in a bundle are built around some base
	// template (that defined structure of the page), DefaultTemplate can be set
	// to the name of that base template.
	//
	// If DefaultTemplate is empty, Render(...) will use Execute(...) instead of
	// ExecuteTemplate(...).
	DefaultTemplate string

	// DefaultArgs generates default arguments to use when rendering templates.
	//
	// Additional arguments passed to Render will be merged on top of the
	// default ones. DefaultArgs is called each time Render is called.
	//
	// Extra will be whatever is passed to Render(...) or MustRender(...). Usually
	// (when installing the bundle into the context via WithTemplates(...)
	// middleware) Extra contains information about the request being processed.
	DefaultArgs func(c context.Context, e *Extra) (Args, error)
	// contains filtered or unexported fields
}

Bundle is a bunch of templates lazily loaded at the same time. They may share associated templates. Bundle is injected into the context.

func (*Bundle) EnsureLoaded

func (b *Bundle) EnsureLoaded(c context.Context) error

EnsureLoaded loads all the templates if they haven't been loaded yet.

func (*Bundle) Get

func (b *Bundle) Get(name string) (*template.Template, error)

Get returns the loaded template given its name or error if not found.

The bundle must be loaded by this point (via call to EnsureLoaded).

func (*Bundle) MustRender

func (b *Bundle) MustRender(c context.Context, e *Extra, out io.Writer, name string, args Args)

MustRender renders the template into the output writer or panics.

It never writes partial output. It also panics if attempt to write to the output fails.

The bundle must be loaded by this point (via call to EnsureLoaded).

func (*Bundle) Render

func (b *Bundle) Render(c context.Context, e *Extra, name string, args Args) ([]byte, error)

Render finds template with given name and calls its Execute or ExecuteTemplate method (depending on the value of DefaultTemplate).

It passes the given context and Extra verbatim to DefaultArgs(...). If DefaultArgs(...) doesn't access either of them, it is fine to pass nil instead.

It always renders output into byte buffer, to avoid partial results in case of errors.

The bundle must be loaded by this point (via call to EnsureLoaded).

type Extra

type Extra struct {
	Request *http.Request
	Params  httprouter.Params
}

Extra is passed to DefaultArgs, it contains additional information about the request being processed (usually populated by the middleware).

Must be treated as read only.

type Loader

type Loader func(context.Context, template.FuncMap) (map[string]*template.Template, error)

Loader knows how to load template sets.

func AssetsLoader

func AssetsLoader(assets map[string]string) Loader

AssetsLoader returns Loader that loads templates from the given assets map.

The directory with templates is expected to have special structure:

• 'pages/' contain all top-level templates that will be loaded
• 'includes/' contain templates that will be associated with every top-level template from 'pages/'.
• 'widgets/' contain all standalone templates that will be loaded without templates from 'includes/'

Only templates from 'pages/' and 'widgets/' are included in the output map.

func FileSystemLoader

func FileSystemLoader(fs fs.FS) Loader

FileSystemLoader returns Loader that loads templates from file system.

The directory with templates is expected to have special structure:

• 'pages/' contain all top-level templates that will be loaded
• 'includes/' contain templates that will be associated with every top-level template from 'pages/'.
• 'widgets/' contain all standalone templates that will be loaded without templates from 'includes/'

Only templates from 'pages/' and 'widgets/' are included in the output map.