stencil

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, 2018 License: Apache-2.0 Imports: 15 Imported by: 0

README

Caddy Stencil

Stencil is currently not stable and not recommended for use in production!

Stencil is a templating middleware for Caddy server. Stencil can process three types of input: raw HTML (or any other text-based format), raw HTML with JSON, YAML or TOML front matter, and valid JSON documents. Input can be from files or the output of another directive such as the Proxy directive.

Stencil processes input and runs it through pre-defined templates. Any JSON or front matter data is placed in the .Doc.data variable and the document body is placed in .Doc.body and are available to templates. The entire body of HTML input (without front matter) will is placed in the .Doc.body variable. The variable .Doc.title is either assigned by a root level JSON or front matter entry of "title" or automatically generated based on the file name.

Syntax

stencil [basepath] {
	ext         extensions...
	template    [name] path
}
  • basepath is the base path to match. Stencil will not activate if the request URL is not prefixed with this path. Default is site root.
  • extensions... is a space-delimited list of file extensions to process with Stencil (defaults to .html, and .json).
  • template defines a template with the given name to be at the given path. To specify the default template, omit name. Content can choose a template by using the name in its front matter or JSON.

Processing HTML

Stencil can be used to inject raw HTML or text into templates. This may be useful for integrating legacy systems that don't have a JSON API. The entire body of the document will be placed into the .Doc.body variable for use in your templates.

WARNING: Injecting raw HTML into a template can be dangerous if the source of the HTML is from an untrusted source. Take precautions and make sure your input is trustworthy before injecting it into your template. If you can't trust your input because you don't control it (for example, text input from a public API or website), be sure to use the html, js, or urlquery functions built into text/template to sanitize your input!

Processing HTML with Front Matter

In addition to processing raw HTML (or text) as outlined above, Stencil will process documents with JSON, YAML or TOML front matter placed at the beginning of the document. The data in the front matter is placed in the .Doc.data variable to be used in your templates. The document body is placed in .Doc.body to be used in templates.

Processing JSON Files and APIs

Stencil can be used to process valid JSON either from files or a live JSON API if used in conjunction with the Proxy directive. For Stencil to handle JSON files, the file name must contain the .json extension or, if using Proxy, must have either a .json extension or have a MIME type of "application/json".

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetDefaultTemplate 

func GetDefaultTemplate() *template.Template

GetDefaultTemplate returns the default template.

func SetTemplate 

func SetTemplate(t *template.Template, name, filename string) error

SetTemplate reads in the template with the filename provided. If the file does not exist or is not parsable, it will return an error.

func Setup 

func Setup(c *caddy.Controller) error

setup configures a new Stencil middleware instance.

Types

type CachedFileInfo 

type CachedFileInfo struct {
	Path string
	Fi   os.FileInfo
}

type Config 

type Config struct {
	// Base path to match
	PathScope string

	// List of extensions to consider as stencil files
	Extensions map[string]struct{}

	// Template(s) to render with
	Template *template.Template

	// a pair of template's name and its underlying file information
	TemplateFiles map[string]*CachedFileInfo
}

Config stores stencil middleware configurations.

func (*Config) Stencil 

func (c *Config) Stencil(title string, r io.Reader, ctx httpserver.Context) ([]byte, error)

Stencil processes the contents of a page in r. It parses the metadata (if any) and uses the template (if found).

type Data 

type Data struct {
	httpserver.Context
	Doc   map[string]interface{}
	Files []FileInfo
}

Data represents a stencil document.

func (Data) Include 

func (d Data) Include(filename string, args ...interface{}) (string, error)

Include "overrides" the embedded httpserver.Context's Include() method so that included files have access to d's fields. Note: using {{template 'template-name' .}} instead might be better.

type FileInfo 

type FileInfo struct {
	os.FileInfo
	// contains filtered or unexported fields
}

FileInfo represents a file in a particular server context. It wraps the os.FileInfo struct.

type Stencil 

type Stencil struct {
	// Server root
	Root string

	// Jail the requests to site root with a mock file system
	FileSys http.FileSystem

	// Next HTTP handler in the chain
	Next httpserver.Handler

	// The list of stencil configurations
	Configs []*Config

	BufPool *sync.Pool
}

func (Stencil) ServeHTTP 

func (st Stencil) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)

ServeHTTP implements the http.Handler interface.

Source Files

View all Source files

Directories

Path Synopsis

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.