Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type TemplateContext ¶ added in v2.4.0
type TemplateContext struct {
Root http.FileSystem
Req *http.Request
Args []interface{} // defined by arguments to funcInclude
RespHeader WrappedHeader
// 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.
Delimiters []string `json:"delimiters,omitempty"`
}
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.
[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`
Access arguments passed to this page/context, for example as the result of a `include`.
``` {{.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"}} ```
##### `include`
Includes the contents of another file. 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.
``` {{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"}} ```
##### `.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"}} ```
##### `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"}} ```
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