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
- type WrappedHeader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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.
type WrappedHeader ¶
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.
Source Files