xtemplate_caddy

README

xtemplate_caddy module

xtemplate_caddy adapts xtemplate for use in the Caddy web server by:

1. Publishing as a caddy module named http.handlers.xtemplate
2. Exposing it as a caddyhttp.MiddlewareHandler that can serve as a route handler using the xtemplate handler middleware definition.
3. Adapts Caddyfile configuration to XTemplate config.

See xtemplate readme for syntax details.

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%2Fxtemplate

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

Caddy is a very capable 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, etc

Config

Here are the xtemplate configs 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.
}

Build

To build xtemplate_caddy locally, install xcaddy, then build from the directory root:

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

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

# build with CGO in order to use the sqlite3 db driver
CGO_ENABLED=1 xcaddy build --with github.com/infogulch/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/xtemplate

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

Documentation

Index

• type XTemplateModule
  • func (XTemplateModule) CaddyModule() caddy.ModuleInfo
  • func (m *XTemplateModule) Cleanup() error
  • func (m *XTemplateModule) Provision(ctx caddy.Context) error
  • func (m *XTemplateModule) ServeHTTP(w http.ResponseWriter, r *http.Request, _ caddyhttp.Handler) error
  • func (m *XTemplateModule) Validate() error

Types

type XTemplateModule

type XTemplateModule struct {
	// The root path from which to load template files within the selected
	// filesystem (the native filesystem by default). Default is the current
	// working directory.
	TemplateRoot string `json:"template_root,omitempty"`

	// The root path to reference files from within template funcs. The default,
	// empty string means the local filesystem funcs in templates are disabled.
	ContextRoot string `json:"context_root,omitempty"`

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

	// The database driver and connection string. If set, must be precicely two
	// elements: the driver name and the connection string.
	Database struct {
		Driver  string `json:"driver,omitempty"`
		Connstr string `json:"connstr,omitempty"`
	} `json:"database,omitempty"`

	Config map[string]string `json:"config,omitempty"`

	FuncsModules []string `json:"funcs_modules,omitempty"`
	// contains filtered or unexported fields
}

func (XTemplateModule) CaddyModule

func (XTemplateModule) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*XTemplateModule) Cleanup

func (m *XTemplateModule) Cleanup() error

Cleanup discards resources held by t. Implements caddy.CleanerUpper.

func (*XTemplateModule) Provision

func (m *XTemplateModule) Provision(ctx caddy.Context) error

Provision provisions t. Implements caddy.Provisioner.

func (*XTemplateModule) ServeHTTP

func (m *XTemplateModule) ServeHTTP(w http.ResponseWriter, r *http.Request, _ caddyhttp.Handler) error

func (*XTemplateModule) Validate

func (m *XTemplateModule) Validate() error

Validate ensures t has a valid configuration. Implements caddy.Validator.