luci: go.chromium.org/luci/server/templates Index | Files

package templates

import "go.chromium.org/luci/server/templates"

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

Index

Package Files

bundle.go context.go doc.go loaders.go middleware.go

func Get Uses

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 Uses

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 Uses

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 Uses

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 Uses

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.

type Args Uses

type Args map[string]interface{}

Args contains data passed to the template.

func MergeArgs Uses

func MergeArgs(args ...Args) Args

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

type Bundle Uses

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 Uses

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

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

func (*Bundle) Get Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Loader knows how to load template sets.

func AssetsLoader Uses

func AssetsLoader(assets map[string]string) Loader

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

The map 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/'.

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

func FileSystemLoader Uses

func FileSystemLoader(path string) 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/'.

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

Package templates imports 14 packages (graph) and is imported by 14 packages. Updated 2018-10-21. Refresh now. Tools for package owners.