engine

README

The Engine: A Web Theme Engine for Go

This library provides tools for managing themes (a collection of templates and supporting files) for Go. It allows theme chaining and overriding.

This library is oriented toward Web theming using html/template and text/template.

With this library, you can:

• Support numerous themes in one app
• Cascade and override themes
• Provide easy support for re-theming an existing app

Usage

Say you have the following theme directories, with the following files:

themes/
    |
    |- pretty/
    |    |
    |    |- main.tpl
    |
    |- ugly/
    |    |
    |    |- duckling.tpl
    |    |
    |    |- main.css
    |
    |- default/
         |
         |- main.tpl
         |
         |- duckling.tpl
         |
         |- main.css

There are three themes here: themes/pretty, themes/ugly, and themes/default.

There are two types of file: templates (end in .tpl) and assets (don't end in .tpl).

Say we want to apply the pretty theme, but with a backup to the default theme. We never want any ugly theme content.

package main

import "github.com/Masterminds/engine"

func main() {
    engine, err := New("themes/pretty", "themes/default")
    if err != nil {
        // ... handle the error
    }

    // Render the main.tpl, passing the template the data 42.
    // Because of the order of directories passed into New, this will
    // render to `pretty/main.tpl`.
    out, err := e.Render("main.tpl", 42)
    // ... out will have the rendered data.

    // This will use `themes/default/duckling.tpl` because there is no
    // duckling.tpl in the `themes/pretty` directory.
    out, err = e.Render("duckling.tpl", 42)

    // This will find the `main.css` in the `themes/default` folder,
    // since none exists in `themes/pretty`
    path, err := e.Asset("main.css")
}

In the example above, not that we load two of the three available templates. Engine's primary roll, then, is to negotiate which theme should be used for each individual render call.

Documentation

Index

• Variables
• type Engine
  • func New(paths ...string) (*Engine, error)
  • func NewEngine(paths []string, funcs template.FuncMap, options []string) (*Engine, error)
  • func (e *Engine) Asset(name string) (string, error)
  • func (e *Engine) Dirs() []string
  • func (e *Engine) Paths() []string
  • func (e *Engine) Render(name string, data interface{}) (string, error)

Variables

var (
	// NoTemplateFound indicates that a desired template cannot be located.
	NoTemplateFound = errors.New("no template found")
	// NoAssetFound indicates that no asset could be loaded.
	NoAssetFound = errors.New("no asset found")
	// IllegalName indicates that a name contains illegal characters or patterns.
	IllegalName = errors.New("name contains illegal patterns")
)

var NamedTemplateSeparator = "#"

Types

type Engine

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

func New

func New(paths ...string) (*Engine, error)

New creates a new *Template and processes the given directories.

Each path should point to a "theme" directory. That directory is scanned for templates, which are compiled immediately and then cached.

Paths are normalized, but the resulting normalized version cannot have a relative path. So the path "foo/bar/.." is fine, and will evaluate to "foo", but the path "foo/../.." is not okay, as it will evaluate to "..", which represents a potential security risk.

Each path is scanned for files that end with the extension '.tpl'. Directories are not scanned recursively. Any other files or directories are ignored.

For convenience, the engine supports an additional set of template functions as defined in Sprig:

https://github.com/Masterminds/sprig

These can be disabled by not passing the Sprig functions into NewEngine.

func NewEngine

func NewEngine(paths []string, funcs template.FuncMap, options []string) (*Engine, error)

NewEngine constructs a new *Engine. NewEngine provides more control over the template engine than New.

- funcMap is passed to the template. - options are passed to the template.

func (*Engine) Asset

func (e *Engine) Asset(name string) (string, error)

Asset returns the first matching asset path.

An asset is a non-template file or directory in a theme directory. This function returns the string path of the first path that matches.

An asset path is only returned if the asset exists and can be stat'ed.

func (*Engine) Dirs

func (e *Engine) Dirs() []string

Dirs returns a list of directories that this Engine knows about.

Directories are presented in their cleaned, but not absolute, form.

func (*Engine) Paths

func (e *Engine) Paths() []string

Paths returns all know template paths.

func (*Engine) Render

func (e *Engine) Render(name string, data interface{}) (string, error)

Render looks for a template with the given name, then executes it with the given data.

The 'name' parameter should be a relative template name (foo.tpl). This will look through all of the known templates and execute the first match found. Traversal order is the order in which the templates were added.

The 'data' will be passed into the template unaltered.

If the renderer cannot find a template, it returns NoTemplateFound. If the template cannot be rendered, it may return a different error.