html

README

html

This Go package can load, compose and render HTML templates. It's a small layer on top of 'html/template'.

Features

• fluent API: easily compose templates into sets
• auto-reloading: reload templates on page refresh
• redefinition: define a default and overwrite it later
• validation: ensure completeness at time of creation (not rendering)
• helper functions: e.g. use 'runTemplate' to execute an arbitrary template
• caching: templates are only parsed once

Example

import "github.com/stephanos/html"

// specify template source directories, enable auto-reload
conf := html.Config{Directories: []string{"views"}, AutoReload: true}

// scan for available templates
loader, _ := html.NewLoader(conf)

// create two sets: a re-usable and a specific one
baseSet := loader.NewSet().Add("layout", "partials/header", "partials/footer")
helloSet := loader.NewSet().AddSet(baseSet).Add("pages/hello")

// create executable view, making sure all template placeholders are defined
view := helloSet.ViewMust()

// execute the template and print the result to a Writer
http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
    view.Write(w, "World") 
})

ToDos

• render any error to HTML (+ display snippet of template source)
• add method to trigger a re-build of all views
• allow custom template file extension (other than .html)
• allow custom template parser

Install

go get github.com/stephanos/html

Documentation

godoc.org

License

MIT (see LICENSE).

Documentation

Index

• type Config
• type Loader
  • func NewLoader(conf Config) (l *Loader, err error)
  • func (l *Loader) AddFile(name, filePath string) *Loader
  • func (l *Loader) AddText(name string, content string) *Loader
  • func (l *Loader) NewSet() *Set
  • func (l *Loader) Sources() []*Source
• type Set
  • func (s *Set) Add(files ...string) *Set
  • func (s *Set) AddFunc(name string, fn interface{}) *Set
  • func (s *Set) AddFuncs(funcMap map[string]interface{}) *Set
  • func (s *Set) AddSet(set *Set) *Set
  • func (s *Set) AddSets(sets ...*Set) *Set
  • func (s *Set) Funcs() map[string]interface{}
  • func (s *Set) Set(name, file string) *Set
  • func (s *Set) Sources() []Source
  • func (s *Set) View() (*View, error)
  • func (s *Set) ViewMust() *View
• type Source
• type View
  • func (v *View) HTML(data ...interface{}) (string, error)
  • func (v *View) Write(wr io.Writer, data ...interface{}) error

Types

type Config

type Config struct {

	// Directories define the file paths to search for templates,
	// ordered by descending priority.
	Directories []string

	// AutoReload is whether the templates should be reloaded on rendering.
	// This is useful in development, but should be disabled in production.
	AutoReload bool

	// DelimLeft is the delimiter that marks the start of a template action.
	DelimLeft string

	// DelimRight is the delimiter that marks the stop of a template action.
	DelimRight string
}

Config controls the behaviour of the template loading and rendering.

type Loader

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

Loader collects the available template sources. It creates new sets and triggers the template parsing.

func NewLoader

func NewLoader(conf Config) (l *Loader, err error)

NewLoader creates a new loader. It scans the provided source directories and collects all available template sources.

func (*Loader) AddFile

func (l *Loader) AddFile(name, filePath string) *Loader

AddFile adds a file-based template source. It overwrites any existing source with the same name.

func (*Loader) AddText

func (l *Loader) AddText(name string, content string) *Loader

AddText adds a text-based template source. It overwrites any existing source with the same name.

func (*Loader) NewSet

func (l *Loader) NewSet() *Set

NewSet returns a new initialized set.

func (*Loader) Sources

func (l *Loader) Sources() []*Source

Sources returns the sources found by scanning the provided directories.

type Set

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

Set is a collection of template sources. It allows to create a View from its sources.

func (*Set) Add

func (s *Set) Add(files ...string) *Set

Add appends a template source, identified by its file path, to the set. A copy of the set is returned.

func (*Set) AddFunc

func (s *Set) AddFunc(name string, fn interface{}) *Set

AddFunc appends a named function to the set's function map. It is legal to overwrite elements of the map. A copy of the set is returned.

func (*Set) AddFuncs

func (s *Set) AddFuncs(funcMap map[string]interface{}) *Set

AddFuncs appends the functions of the passed-in function map to the set's function map. It is legal to overwrite elements of the map. A copy of the set is returned.

func (*Set) AddSet

func (s *Set) AddSet(set *Set) *Set

AddSet appends the template sources of another set to this one. A copy of the set is returned.

func (*Set) AddSets

func (s *Set) AddSets(sets ...*Set) *Set

AddSets appends the template sources of other sets to this one. It returns a copy of the Set.

func (*Set) Funcs

func (s *Set) Funcs() map[string]interface{}

Funcs returns a copy of the set's function map.

func (*Set) Set

func (s *Set) Set(name, file string) *Set

Set appends a template source, identified by its file path and name, to the set. A copy of the set is returned.

func (*Set) Sources

func (s *Set) Sources() []Source

Sources returns a copy of the set's template sources.

func (*Set) View

func (s *Set) View() (*View, error)

View creates a new view from the set's template sources. If an error occurs, the returned view is nil.

func (*Set) ViewMust

func (s *Set) ViewMust() *View

ViewMust creates a new view from the set's template sources. It panics if an error occurs.

type Source

type Source struct {
	Content  string
	FilePath string
	Name     string
}

Source is a template data source. It contains an optional path to the source's file source.

type View

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

A View can be rendered to HTML text.

func (*View) HTML

func (v *View) HTML(data ...interface{}) (string, error)

HTML applies the parsed template to the specified data object, returning the result as a text.

func (*View) Write

func (v *View) Write(wr io.Writer, data ...interface{}) error

Write applies the parsed template to the specified data object, writing the output to wr.