xtemplate

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2023 License: Apache-2.0 Imports: 36 Imported by: 6

README

caddy-xtemplate is a Caddy module that extends Go's html/template library to be capable enough to host an entire server-side application in it. Designed with the htmx.org js library in mind, which makes server side rendered sites feel as interactive as a Single Page Apps.

⚠️ This project is still in development, expect breaking changes. ⚠️

Table of contents

Features

Query the database directly within template definitions

<ul>
  {{range .Query `SELECT id,name FROM contacts`}}
  <li><a href="/contact/{{.id}}">{{.name}}</a></li>
  {{end}}
</ul>

Note: The html/template library automatically sanitizes inputs, so you can rest easy from basic XSS attacks. Note: if you generate some html that you do trust, it's easy to inject if you intend to.

Define templates and import content from other files

<html>
  <title>Home</title>
  <!-- import the contents of a file -->
  {{template "/shared/_head.html" .}}

  <body>
    <!-- invoke a custom template defined anywhere -->
    {{template "navbar" .}}
    ...
  </body>
</html>

File-based routing & custom routes

GET requests for any file will invoke the template file at that path. Except files that start with _ which are not routed, this lets you define templates that only other templates can invoke.

.
├── index.html          GET /
├── todos.html          GET /todos
├── admin
│   └── settings.html   GET /admin/settings
└── shared
    └── _head.html      (not routed)

Create custom route handlers by defining a template with a name matching the pattern <method> <path>. Use httprouter syntax for path parameters and wildcards, which are made available in the template as values in the .Param key while serving a request.

<!-- match on path parameters -->
{{define "GET /contact/:id"}}
{{$contact := .QueryRow `SELECT name,phone FROM contacts WHERE id=?` (.Params.ByName "id")}}
<div>
  <span>Name: {{.name}}</span>
  <span>Phone: {{.phone}}</span>
</div>
{{end}}

<!-- match on any http method -->
{{define "DELETE /contact/:id"}}
{{$_ := .Exec `DELETE from contacts WHERE id=?` (.Params.ByName "id")}}
{{.RespStatus 204}}
{{end}}

Automatic reload

Templates are reloaded and validated automatically as soon as they are modified, no need to restart the server. If there's a syntax error it continues to serve the old version and prints the loading error out in Caddy's logs.

Ctrl+S > Alt+Tab > F5

Showcase

Quickstart

Download caddy with all standard modules, plus the xtemplate module (!important) from Caddy's build and download server:

https://caddyserver.com/download?package=github.com%2Finfogulch%2Fcaddy-xtemplate

Write your caddy config and use the xtemplate http handler:

:8080

route {
    xtemplate {
        template_root templates
    }
}

Write .html files in the root directory specified in your Caddy config.

Run caddy with your config: caddy run --config Caddyfile

Remember Caddy is a super http server, check out the caddy docs for features you may want to layer on top. Examples: serving static files (css/js libs), set up an auth proxy, caching, rate limiting, automatic https, and more!

Config

xtemplate is configured through caddy's configuration system. Here are the config fields available to a Caddyfile:

xtemplate {
    template_root <root directory where template files are loaded>
    context_root <root directory that template funcs have access to>
    delimiters <left> <right>         # defaults: {{ and }}
    database {                        # default empty, no db available
        driver <driver>               # driver and connstr are passed directly to sql.Open
        connstr <connection string>   # check your sql driver for connstr details
    }
    config {                          # a map of configs, accessible in the template as .Config
      key1 value1
      key2 value2
    }
    funcs_modules <mod1> <mod2>       # a list of caddy modules under the `xtemplate.funcs.*`
                                      # namespace that implement the FuncsProvider interface,
                                      # to add custom funcs to the Template FuncMap.
}

These sql drivers are available by default. Modify db.go and recompile xtemplate to include your preferred drivers.

  • mattn/sqlite3 (requires building with CGO_ENABLED=1, not available from the caddy build server)
  • cznic/sqlite (available without CGo, including from the caddy build server)

Template syntax

Template syntax uses Go's html/template module, and extends it with custom functions and useful context.

Context values

The dot context {{.}} set on the main template handler provides request-specific data and stateful actions. See tplcontext.go for details.

  • Request and response related fields and fields
    • .Req is the current HTTP request struct, 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
    • .OriginalReq is the original, unmodified, un-rewritten request as it originally came in over the wire. Has the same fields as .Req.
    • .Params is a list of path parameters extracted from the url based on the current route, see custom routes. {{.Params.ByName "id"}}
    • .RemoteIP is the client's IP address. {{.RemoteIP}}
    • .Host is the hostname portion (no port) of the Host header of the HTTP request.
    • .Cookie Gets the value of a cookie by name. {{.Cookie "cookiename"}}
    • .Placeholder gets a caddy "placeholder variable". The braces ({}) have to be omitted.
    • .RespStatus Set the status code of the current response. {{.RespStatus 201}}
    • .RespHeader.Add Adds a header field to the HTTP response. {{.RespHeader.Add "Field-Name" "val"}}
    • .RespHeader.Set Sets a header field on the HTTP response, replacing any existing value.
    • .RespHeader.Del Deletes a header field on the HTTP response.
  • File related funcs. File operations are rooted at the directory specified by the context_root config option.
    • .ReadFile reads and returns the contents of a file, as-is. Note that the contents are NOT escaped, so you should only read trusted files.
    • .ListFiles returns a list of the files in the given directory.
    • .FileExists returns true if filename can be opened successfully.
    • .StatFile returns Stat of a filename.
  • Database related funcs. All funcs accept a query string and any number of parameters. Prefer using parameters over building the query string dynamically.
    • .Exec executes a statment
    • .QueryRows executes a query and returns all rows in a big []map[string]any.
    • .QueryRow executes a query, which must return one row, and returns the map[string]any.
    • .QueryVal executes a query, which must return one row and one column, and returns the value of the column.
  • Other
    • .Template evaluate the template name with the given context and return the result as a string.
    • .Funcs returns a list of all the custom FuncMap funcs that are available to call. Useful in combination with the try func.
    • .Config is a map of config strings set in the Caddyfile. See Config.

Functions

There are built-in functions that perform actions that are unrelated to a specific request. See funcs.go for details.

Go stdlib template functions

See text/template#Functions.

Expand for a stdlib funcs documentation.
  • and Returns the boolean AND of its arguments by returning the first empty argument or the last argument. That is, "and x y" behaves as "if x then y else x." Evaluation proceeds through the arguments left to right and returns when the result is determined.
  • call Returns the result of calling the first argument, which must be a function, with the remaining arguments as parameters. Thus "call .X.Y 1 2" is, in Go notation, dot.X.Y(1, 2) where Y is a func-valued field, map entry, or the like. The first argument must be the result of an evaluation that yields a value of function type (as distinct from a predefined function such as print). The function must return either one or two result values, the second of which is of type error. If the arguments don't match the function or the returned error value is non-nil, execution stops.
  • html Returns the escaped HTML equivalent of the textual representation of its arguments. This function is unavailable in html/template, with a few exceptions.
  • index Returns the result of indexing its first argument by the following arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each indexed item must be a map, slice, or array.
  • slice slice returns the result of slicing its first argument by the remaining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2], while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3" is x[1:2:3]. The first argument must be a string, slice, or array.
  • js Returns the escaped JavaScript equivalent of the textual representation of its arguments.
  • len Returns the integer length of its argument.
  • not Returns the boolean negation of its single argument.
  • or Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument, that is, "or x y" behaves as "if x then x else y". Evaluation proceeds through the arguments left to right and returns when the result is determined.
  • print An alias for fmt.Sprint
  • printf An alias for fmt.Sprintf
  • println An alias for fmt.Sprintln
  • urlquery Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. This function is unavailable in html/template, with a few exceptions.

Sprig library template functions

See the Sprig documentation for details: Sprig Function Documentation.

Expand for a listing of Sprig funcs.

xtemplate functions

  • markdown Renders the given Markdown text as HTML and returns it. This uses the Goldmark library, which is CommonMark compliant. It also has these extensions enabled: Github Flavored Markdown, Footnote, and syntax highlighting provided by Chroma.
  • 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.
    • .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}}
  • sanitizeHtml Uses bluemonday to sanitize strings with html content. {{sanitizeHtml "strict" "Shows <b>only</b> text content"}}
    • First parameter is the name of the chosen sanitization policy. "strict" = StrictPolicy(), "ugc" = UGCPolicy() for 'user generated content', "externalugc" = UGCPolicy() + disallow relative urls + add target=_blank to urls.
    • Second parameter is the content to sanitize.
    • Returns the string as a template.HTML type which can be output directly into the document without trustHtml.
  • humanize Transforms size and time inputs to a human readable format using the go-humanize library. Call with two parameters, the format type and the value to format. Format types are:
    • size which turns an integer amount of bytes into a string like 2.3 MB, for example: {{humanize "size" "2048000"}}
    • time which turns a time string into a relative time string like 2 weeks ago, for example: {{humanize "time" "Fri, 05 May 2022 15:04:05 +0200"}}
  • ksuid returns a 'K-Sortable Globally Unique ID' using segmentio/ksuid
  • idx gets an item from a list, similar to the built-in index, but with reversed args: index first, then array. This is useful to use index in a pipeline, for example: {{generate-list | idx 5}}
  • try takes a function that returns an error in the first argument and calls it with the values from the remaining arguments, and returns the result including any error as struct fields. This enables template authors to handle funcs that return errors within the template definition. Example: {{ $result := try .QueryVal "SELECT 'oops' WHERE 1=0" }}{{if $result.OK}}{{$result.Value}}{{else}}QueryVal requires exactly one row. Error: {{$result.Error}}{{end}}

Development

To work on this project, install xcaddy, then build from the repo root:

# build a caddy executable with the latest version of caddy-xtemplate from github:
xcaddy build --with github.com/infogulch/caddy-xtemplate

# build a caddy executable and override the xtemplate module with your
# modifications in the current directory:
xcaddy build --with github.com/infogulch/caddy-xtemplate=.

# build with CGO in order to use the sqlite3 db driver
CGO_ENABLED=1 xcaddy build --with github.com/infogulch/caddy-xtemplate

# build enable the sqlite_json build tag to get json funcs
GOFLAGS='-tags="sqlite_json"' CGO_ENABLED=1 xcaddy build --with github.com/infogulch/caddy-xtemplate

TZ=UTC git --no-pager show --quiet --abbrev=12 --date='format-local:%Y%m%d%H%M%S' --format="%cd-%h"

Project lineage and license

The idea for this project started in infogulch/go-htmx (now archived), which included the first implementations of template-name-based routing, exposing sql db functions to templates, and a persistent templates instance shared across requests and reloaded when template files changed.

go-htmx was refactored and rebased on top of the templates module from the Caddy server to create caddy-xtemplate in order to get a jump start on broader web server features without having to implement them from scratch.

caddy-xtemplate is licensed under the Apache 2.0 license. See LICENSE

Documentation

Overview

caddy-xtemplate is a Caddy module that extends Go's html/template to be capable enough to host an entire server-side application in it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type FuncHandlerError 

type FuncHandlerError struct {
	// contains filtered or unexported fields
}

func (FuncHandlerError) Error 

func (fhe FuncHandlerError) Error() string

func (FuncHandlerError) ServeHTTP 

func (fhe FuncHandlerError) ServeHTTP(w http.ResponseWriter, r *http.Request)

type HandlerError 

type HandlerError interface {
	Error() string
	ServeHTTP(w http.ResponseWriter, r *http.Request)
}

func NewHandlerError 

func NewHandlerError(name string, fn func(w http.ResponseWriter, r *http.Request)) HandlerError

type ReturnError 

type ReturnError struct{}

func (ReturnError) Error 

func (ReturnError) Error() string

type TemplateContext 

type TemplateContext struct {
	Req        *http.Request
	Params     pathmatcher.Params
	RespHeader WrappedHeader
	RespStatus func(int) string
	Config     map[string]string
	// contains filtered or unexported fields
}

TemplateContext is the TemplateContext with which HTTP templates are executed.

func (*TemplateContext) Cookie 

func (c *TemplateContext) Cookie(name string) string

Cookie gets the value of a cookie with name name.

func (*TemplateContext) Exec 

func (c *TemplateContext) Exec(query string, params ...any) (result sql.Result, err error)

func (*TemplateContext) FileExists 

func (c *TemplateContext) FileExists(filename string) (bool, error)

funcFileExists returns true if filename can be opened successfully.

func (*TemplateContext) Funcs 

func (c *TemplateContext) Funcs() template.FuncMap

func (*TemplateContext) Host 

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

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

func (*TemplateContext) ListFiles 

func (c *TemplateContext) ListFiles(name string) ([]string, error)

ListFiles reads and returns a slice of names from the given directory relative to the root of c.

func (*TemplateContext) QueryRow 

func (c *TemplateContext) QueryRow(query string, params ...any) (map[string]any, error)

func (*TemplateContext) QueryRows 

func (c *TemplateContext) QueryRows(query string, params ...any) (rows []map[string]any, err error)

func (*TemplateContext) QueryStats 

func (c *TemplateContext) QueryStats() struct {
	Count         int
	TotalDuration time.Duration
}

func (*TemplateContext) QueryVal 

func (c *TemplateContext) QueryVal(query string, params ...any) (any, error)

func (*TemplateContext) ReadFile 

func (c *TemplateContext) ReadFile(filename string) (string, error)

ReadFile returns the contents of a filename relative to the site root. Note that included files are NOT escaped, so you should only include trusted files. If it is not trusted, be sure to use escaping functions in your template.

func (*TemplateContext) RemoteIP 

func (c *TemplateContext) RemoteIP() string

RemoteIP gets the IP address of the client making the request.

func (*TemplateContext) StatFile 

func (c *TemplateContext) StatFile(filename string) (fs.FileInfo, error)

StatFile returns Stat of a filename

func (*TemplateContext) Template 

func (c *TemplateContext) Template(name string, context any) (string, error)

func (*TemplateContext) WithVars 

func (c *TemplateContext) WithVars(vars map[string]any) TemplateContextVars

type TemplateContextVars 

type TemplateContextVars struct {
	*TemplateContext
	Vars map[string]any
}

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.

type XTemplate 

type XTemplate struct {
	TemplateFS fs.FS
	ContextFS  fs.FS
	ExtraFuncs []template.FuncMap
	DB         *sql.DB
	Config     map[string]string
	Delims     struct{ L, R string }
	Log        *slog.Logger
	// contains filtered or unexported fields
}

func (*XTemplate) Reload 

func (t *XTemplate) Reload() error

func (*XTemplate) ServeHTTP 

func (t *XTemplate) ServeHTTP(w http.ResponseWriter, r *http.Request)

Source Files

View all Source files

Directories

Path Synopsis
app module
caddy module
cmd module
internal module
providers
nats module
register module
test module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.