tmplfunc

README

Package tmplfunc provides an extension of Go templates in which templates can be invoked as if they were functions.

See the package documentation for details.

Documentation

Overview

Package tmplfunc provides an extension of Go templates in which templates can be invoked as if they were functions.

For example, after parsing

{{define "link url text"}}<a href="{{.url}}">{{.text}}</a>{{end}}

this package installs a function named link allowing the template to be invoked as

{{link "https://golang.org" "the Go language"}}

instead of the longer-form (assuming an appropriate function named dict)

{{template "link" (dict "url" "https://golang.org" "text" "the Go language")}}

Function Definitions

The function installed for a given template depends on the name of the defined template, which can include not just a function name but also a list of parameter names. The function name and parameter names must consist only of letters, digits, and underscores, with a leading non-digit.

If there is no parameter list, then the function is expected to take at most one argument, made available in the template body as “.” (dot). If such a function is called with no arguments, dot will be a nil interface value.

If there is a parameter list, then the function requires an argument for each parameter, except for optional and variadic parameters, explained below. Inside the template, the top-level value “.” is a map[string]interface{} in which each parameter name is mapped to the corresponding argument value. A parameter x can therefore be accessed as {{(index . "x")}} or, more concisely, {{.x}}.

The first special case in parameter handling is that a parameter can be made optional by adding a “?” suffix after its name. If the argument list ends before that parameter, the corresponding map entry will be present and set to a nil value. The second special case is that a parameter can be made variadic by adding a “...” suffix after its name. The corresponding map entry contains a []interface{} holding the zero or more arguments corresponding to that parameter.

In the parameter list, required parameters must precede optional parameters, which must in turn precede any variadic parameter.

For example, we can revise the link template given earlier to make the link text optional, substituting the URL when the text is omitted:

{{define "link url text?"}}<a href="{{.url}}">{{or .text .url}}</a>{{end}}

The Go home page is {{link "https://golang.org"}}.

Usage

This package is meant to be used with templates from either the text/template or html/template packages. Given a *template.Template variable t, substitute:

t.Parse(text) -> tmplfunc.Parse(t, text)
t.ParseFiles(list) -> tmplfunc.ParseFiles(t, list)
t.ParseGlob(pattern) -> tmplfunc.ParseGlob(t, pattern)

Parse, ParseFiles, and ParseGlob parse the new templates but also add functions that invoke them, named according to the function signatures. Templates can only invoke functions for templates that have already been defined or that are being defined in the same Parse, ParseFiles, or ParseGlob call. For example, templates in two files x.tmpl and y.tmpl can call each other only if ParseFiles or ParseGlob is used to parse both files in a single call. Otherwise, the parsing of the first file will report that calls to templates in the second file are calling unknown functions.

When used with the html/template package, all function-invoked template calls are treated as invoking templates producing HTML. In order to use a template that produces some other kind of text fragment, the template must be invoked directly using the {{template "name"}} form, not as a function call.

Index

• func Funcs(t Template) error
• func MustParse(t Template, text string)
• func MustParseFiles(t Template, filenames ...string)
• func MustParseGlob(t Template, pattern string)
• func Parse(t Template, text string) error
• func ParseFiles(t Template, filenames ...string) error
• func ParseGlob(t Template, pattern string) error
• type Template

Functions

func Funcs

func Funcs(t Template) error

Funcs installs functions for all the templates in the set containing t. After using t.Clone it is necessary to call Funcs on the result to arrange for the functions to invoke the cloned templates and not the originals.

func MustParse

func MustParse(t Template, text string)

MustParse is like Parse but panics on error.

func MustParseFiles

func MustParseFiles(t Template, filenames ...string)

MustParseFiles is like ParseFiles but panics on error.

func MustParseGlob

func MustParseGlob(t Template, pattern string)

MustParseGlob is like ParseGlob but panics on error.

func Parse

func Parse(t Template, text string) error

Parse is like t.Parse(text), adding functions for the templates defined in text.

func ParseFiles

func ParseFiles(t Template, filenames ...string) error

ParseFiles is like t.ParseFiles(filenames...), adding functions for the parsed templates.

func ParseGlob

func ParseGlob(t Template, pattern string) error

ParseGlob is like t.ParseGlob(pattern), adding functions for the parsed templates.

Types

type Template

type Template interface {
	// Method here only to make most types that are not a *template.Template
	// not implement the interface. The requirement here is to be one of the two
	// template types, not just to have this single method.
	DefinedTemplates() string
	Name() string
}

A Template is a *template.Template, where template refers to either the html/template or text/template package.