Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CustomFunctions ¶ added in v2.5.1
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 ¶ added in v2.4.0
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) Cookie ¶ added in v2.4.0
func (c TemplateContext) Cookie(name string) string
Cookie gets the value of a cookie with name name.
func (TemplateContext) Host ¶ added in v2.4.0
func (c TemplateContext) Host() (string, error)
Host returns the hostname portion of the Host header from the HTTP request.
func (*TemplateContext) NewTemplate ¶ added in v2.4.0
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 ¶ added in v2.4.0
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 ¶ added in v2.4.0
func (c TemplateContext) RemoteIP() string
RemoteIP gets the IP address of the client making the request.
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"`
// 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`.
``` {{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 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`
Imports the contents of another file and adds any template definitions to the template stack. If there are no defitions, the filepath will be the defition name. Any {{ define }} blocks will be accessible by {{ template }} or {{ block }}. Imports must happen before the template or block action is called
**filename.html** ``` {{ define "main" }} content {{ end }} ```
**index.html** ``` {{ import "/path/to/filename.html" }} {{ template "main" }} ```
##### `include`
Includes the contents of another file and renders in-place. Optionally can pass key-value pairs as arguments to be accessed by the included file.
``` {{include "path/to/file.html"}} // no arguments {{include "path/to/file.html" "arg1" 2 "value 3"}} // with arguments ```
##### `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. This uses the [Goldmark](https://github.com/yuin/goldmark) library, which is CommonMark compliant. It also has these plugins enabled: Github Flavored Markdown, Footnote and syntax highlighting provided by [Chroma](https://github.com/alecthomas/chroma).
``` {{markdown "My _markdown_ text"}} ```
##### `.RemoteIP`
Returns the client's IP address.
``` {{.RemoteIP}} ```
##### `.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, 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 `+++`:
``` +++ template = "blog" title = "Blog Homepage" sitename = "A Caddy site" +++ ```
**YAML** is surrounded by `---`:
``` --- template: blog title: Blog Homepage sitename: A Caddy site --- ```
**JSON** is simply `{` and `}`:
```
{
"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`.
``` {{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.
type WrappedHeader ¶ added in v2.4.0
WrappedHeader wraps niladic functions so that they can be used in templates. (Template functions must return a value.)
func (WrappedHeader) Add ¶ added in v2.4.0
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 ¶ added in v2.4.0
func (h WrappedHeader) Del(field string) string
Del deletes a header field. It returns an empty string.
func (WrappedHeader) Set ¶ added in v2.4.0
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.
Source Files