templates

Documentation

Index

• type CustomFunctions
• type TemplateContext
  • func (c TemplateContext) ClientIP() string
  • func (c TemplateContext) Cookie(name string) string
  • func (c TemplateContext) Host() (string, error)
  • func (c *TemplateContext) NewTemplate(tplName string) *template.Template
  • func (c TemplateContext) OriginalReq() http.Request
  • func (c TemplateContext) RemoteIP() string
• type Templates
  • func (Templates) CaddyModule() caddy.ModuleInfo
  • func (t *Templates) Provision(ctx caddy.Context) error
  • func (t *Templates) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (t *Templates) Validate() error
• type WrappedHeader
  • func (h WrappedHeader) Add(field, val string) string
  • func (h WrappedHeader) Del(field string) string
  • func (h WrappedHeader) Set(field, val string) string

Types

type CustomFunctions

type CustomFunctions interface {
	// CustomTemplateFunctions should return the mapping from custom function names to implementations.
	CustomTemplateFunctions() template.FuncMap
}

CustomFunctions is the interface for registering custom template functions.

type TemplateContext

type TemplateContext struct {
	Root        http.FileSystem
	Req         *http.Request
	Args        []any // defined by arguments to funcInclude
	RespHeader  WrappedHeader
	CustomFuncs []template.FuncMap // functions added by plugins
	// contains filtered or unexported fields
}

TemplateContext is the TemplateContext with which HTTP templates are executed.

func (TemplateContext) ClientIP

func (c TemplateContext) ClientIP() string

ClientIP gets the IP address of the real client making the request if the request is trusted (see trusted_proxies), otherwise returns the connection's remote IP.

func (TemplateContext) Cookie

func (c TemplateContext) Cookie(name string) string

Cookie gets the value of a cookie with name.

func (TemplateContext) Host

func (c TemplateContext) Host() (string, error)

Host returns the hostname portion of the Host header from the HTTP request.

func (*TemplateContext) NewTemplate

func (c *TemplateContext) NewTemplate(tplName string) *template.Template

NewTemplate returns a new template intended to be evaluated with this context, as it is initialized with configuration from this context.

func (TemplateContext) OriginalReq

func (c TemplateContext) OriginalReq() http.Request

OriginalReq returns the original, unmodified, un-rewritten request as it originally came in over the wire.

func (TemplateContext) RemoteIP

func (c TemplateContext) RemoteIP() string

RemoteIP gets the IP address of the connection's remote IP.

type Templates

type Templates struct {
	// The root path from which to load files. Required if template functions
	// accessing the file system are used (such as include). Default is
	// `{http.vars.root}` if set, or current working directory otherwise.
	FileRoot string `json:"file_root,omitempty"`

	// The MIME types for which to render templates. It is important to use
	// this if the route matchers do not exclude images or other binary files.
	// Default is text/plain, text/markdown, and text/html.
	MIMETypes []string `json:"mime_types,omitempty"`

	// The template action delimiters. If set, must be precisely two elements:
	// the opening and closing delimiters. Default: `["{{", "}}"]`
	Delimiters []string `json:"delimiters,omitempty"`

	// Extensions adds functions to the template's func map. These often
	// act as components on web pages, for example.
	ExtensionsRaw caddy.ModuleMap `json:"match,omitempty" caddy:"namespace=http.handlers.templates.functions"`
	// contains filtered or unexported fields
}

Templates is a middleware which executes response bodies as Go templates. The syntax is documented in the Go standard library's [text/template package](https://golang.org/pkg/text/template/).

⚠️ Template functions/actions are still experimental, so they are subject to change.

Custom template functions can be registered by creating a plugin module under the `http.handlers.templates.functions.*` namespace that implements the `CustomFunctions` interface.

[All Sprig functions](https://masterminds.github.io/sprig/) are supported.

In addition to the standard functions and the Sprig library, Caddy adds extra functions and data that are available to a template:

##### `.Args`

A slice of arguments passed to this page/context, for example as the result of a [`include`](#include).

``` {{index .Args 0}} // first argument ```

##### `.Cookie`

Gets the value of a cookie by name.

``` {{.Cookie "cookiename"}} ```

##### `env`

Gets an environment variable.

``` {{env "VAR_NAME"}} ```

##### `placeholder`

Gets an [placeholder variable](/docs/conventions#placeholders). The braces (`{}`) have to be omitted.

``` {{placeholder "http.request.uri.path"}} {{placeholder "http.error.status_code"}} ```

##### `.Host`

Returns the hostname portion (no port) of the Host header of the HTTP request.

``` {{.Host}} ```

##### `httpInclude`

Includes the contents of another file, and renders it in-place, by making a virtual HTTP request (also known as a sub-request). The URI path must exist on the same virtual server because the request does not use sockets; instead, the request is crafted in memory and the handler is invoked directly for increased efficiency.

``` {{httpInclude "/foo/bar?q=val"}} ```

##### `import`

Reads and returns the contents of another file, and parses it as a template, adding any template definitions to the template stack. If there are no definitions, the filepath will be the definition name. Any `{{ define }}` blocks will be accessible by `{{ template }}` or `{{ block }}`. Imports must happen before the template or block action is called. Note that the contents are NOT escaped, so you should only import trusted template files.

**filename.html** ``` {{ define "main" }} content {{ end }} ```

**index.html** ``` {{ import "/path/to/filename.html" }} {{ template "main" }} ```

##### `include`

Includes the contents of another file, rendering it in-place. Optionally can pass key-value pairs as arguments to be accessed by the included file. Use [`.Args N`](#args) to access the N-th argument, 0-indexed. Note that the contents are NOT escaped, so you should only include trusted template files.

``` {{include "path/to/file.html"}} // no arguments {{include "path/to/file.html" "arg0" 1 "value 2"}} // with arguments ```

##### `readFile`

Reads and returns the contents of another file, as-is. Note that the contents are NOT escaped, so you should only read trusted files.

``` {{readFile "path/to/file.html"}} ```

##### `listFiles`

Returns a list of the files in the given directory, which is relative to the template context's file root.

``` {{listFiles "/mydir"}} ```

##### `markdown`

Renders the given Markdown text as HTML and returns it. This uses the [Goldmark](https://github.com/yuin/goldmark) library, which is CommonMark compliant. It also has these extensions enabled: GitHub Flavored Markdown, Footnote, and syntax highlighting provided by [Chroma](https://github.com/alecthomas/chroma).

``` {{markdown "My _markdown_ text"}} ```

##### `.RemoteIP`

Returns the connection's IP address.

``` {{.RemoteIP}} ```

##### `.ClientIP`

Returns the real client's IP address, if `trusted_proxies` was configured, otherwise returns the connection's IP address.

``` {{.ClientIP}} ```

##### `.Req`

Accesses the current HTTP request, which has various fields, including:

• `.Method` - the method
• `.URL` - the URL, which in turn has component fields (Scheme, Host, Path, etc.)
• `.Header` - the header fields
• `.Host` - the Host or :authority header of the request

``` {{.Req.Header.Get "User-Agent"}} ```

##### `.OriginalReq`

Like [`.Req`](#req), except it accesses the original HTTP request before rewrites or other internal modifications.

##### `.RespHeader.Add`

Adds a header field to the HTTP response.

``` {{.RespHeader.Add "Field-Name" "val"}} ```

##### `.RespHeader.Del`

Deletes a header field on the HTTP response.

``` {{.RespHeader.Del "Field-Name"}} ```

##### `.RespHeader.Set`

Sets a header field on the HTTP response, replacing any existing value.

``` {{.RespHeader.Set "Field-Name" "val"}} ```

##### `httpError`

Returns an error with the given status code to the HTTP handler chain.

``` {{if not (fileExists $includedFile)}}{{httpError 404}}{{end}} ```

##### `splitFrontMatter`

Splits front matter out from the body. Front matter is metadata that appears at the very beginning of a file or string. Front matter can be in YAML, TOML, or JSON formats:

**TOML** front matter starts and ends with `+++`:

```toml +++ template = "blog" title = "Blog Homepage" sitename = "A Caddy site" +++ ```

**YAML** is surrounded by `---`:

```yaml --- template: blog title: Blog Homepage sitename: A Caddy site --- ```

**JSON** is simply `{` and `}`:

```json { "template": "blog", "title": "Blog Homepage", "sitename": "A Caddy site" } ```

The resulting front matter will be made available like so:

- `.Meta` to access the metadata fields, for example: `{{$parsed.Meta.title}}` - `.Body` to access the body after the front matter, for example: `{{markdown $parsed.Body}}`

##### `stripHTML`

Removes HTML from a string.

``` {{stripHTML "Shows <b>only</b> text content"}} ```

##### `humanize`

Transforms size and time inputs to a human readable format. This uses the [go-humanize](https://github.com/dustin/go-humanize) library.

The first argument must be a format type, and the last argument is the input, or the input can be piped in. The supported format types are: - **size** which turns an integer amount of bytes into a string like `2.3 MB` - **time** which turns a time string into a relative time string like `2 weeks ago`

For the `time` format, the layout for parsing the input can be configured by appending a colon `:` followed by the desired time layout. You can find the documentation on time layouts [in Go's docs](https://pkg.go.dev/time#pkg-constants). The default time layout is `RFC1123Z`, i.e. `Mon, 02 Jan 2006 15:04:05 -0700`.

##### `pathEscape`

Passes a string through `url.PathEscape`, replacing characters that have special meaning in URL path parameters (`?`, `&`, `%`).

Useful e.g. to include filenames containing these characters in URL path parameters, or use them as an `img` element's `src` attribute.

``` {{pathEscape "50%_valid_filename?.jpg"}} ```

``` {{humanize "size" "2048000"}} {{placeholder "http.response.header.Content-Length" | humanize "size"}} {{humanize "time" "Fri, 05 May 2022 15:04:05 +0200"}} {{humanize "time:2006-Jan-02" "2022-May-05"}} ```

func (Templates) CaddyModule

func (Templates) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Templates) Provision

func (t *Templates) Provision(ctx caddy.Context) error

Provision provisions t.

func (*Templates) ServeHTTP

func (t *Templates) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

func (*Templates) Validate

func (t *Templates) Validate() error

Validate ensures t has a valid configuration.

type WrappedHeader

type WrappedHeader struct{ http.Header }

WrappedHeader wraps niladic functions so that they can be used in templates. (Template functions must return a value.)

func (WrappedHeader) Add

func (h WrappedHeader) Add(field, val string) string

Add adds a header field value, appending val to existing values for that field. It returns an empty string.

func (WrappedHeader) Del

func (h WrappedHeader) Del(field string) string

Del deletes a header field. It returns an empty string.

func (WrappedHeader) Set

func (h WrappedHeader) Set(field, val string) string

Set sets a header field value, overwriting any other values for that field. It returns an empty string.