Documentation ¶
Overview ¶
Package templateManager simplifies the use of Go's standard library `text/template` for use with HTML templates. It DOES NOT use the `html/template` package to avoid over-zealous HTML escaping (good for security, terrible for usability).
It automates the process of choosing which files to group together for parsing, and builds a cache of each entry template file complete with all of its dependencies.
It does this by allowing files to "extend" their layout templates without manually specifying all bundle files (or including everything via the built-in `template` function. Instead it adds a new tag:
{{ extends "layouts/main.html" }}
which automatically defines the specified file as part of the bundle. It can then follow all instances of the template tag in these two files until all files are in the bundle. This ensures that only the correct blocks exist.
It also defines a second new tag to allow VERY basic variables to be defined within the templates themself and allows them to be overridden via a simple hierarchy:
{{ var "int1" }} 123 {{ end }}
templateManager also comes with a small set of extra convenience functions which may be used or ignored.
Index ¶
- func SetConsoleErrors(errors bool)
- func SetConsoleWarnings(warnings bool)
- func SetDefaultDateFormat(format string)
- func SetDefaultDatetimeFormat(format string)
- func SetDefaultTimeFormat(format string)
- func SetHaltOnErrors(errors bool)
- func SetHaltOnWarnings(warnings bool)
- func SetTimezoneFixed(name string, offset int)
- func SetTimezoneLocation(location time.Location)
- func SetTimezoneLocationString(location string) error
- type Params
- type Template
- func (t *Template) Delims(left string, right string) *Template
- func (t *Template) Execute(wr io.Writer, data any) error
- func (t *Template) ExecuteTemplate(wr io.Writer, name string, data any) error
- func (t *Template) Funcs(funcs map[string]any) *Template
- func (t *Template) InitHtml(name string) *HT.Template
- func (t *Template) InitText(name string) *TT.Template
- func (t *Template) Lookup(name string) *Template
- func (t *Template) NewSubTemplate(name string) *Template
- func (t *Template) Option(opt ...string) *Template
- func (t *Template) Parse(text string) (*Template, error)
- func (t *Template) Type() string
- type TemplateManager
- func (tm *TemplateManager) AddComponentDirectories(directories []string) *TemplateManager
- func (tm *TemplateManager) AddComponentDirectory(directory string) *TemplateManager
- func (tm *TemplateManager) AddFunction(name string, function any) *TemplateManager
- func (tm *TemplateManager) AddFunctions(functions map[string]any) *TemplateManager
- func (tm *TemplateManager) AddParam(templateName string, name string, value any) *TemplateManager
- func (tm *TemplateManager) AddParams(templateName string, params Params) *TemplateManager
- func (tm *TemplateManager) Debug(debug bool) *TemplateManager
- func (tm *TemplateManager) Delimiters(left string, right string) *TemplateManager
- func (tm *TemplateManager) ExcludeDirectories(directories []string) *TemplateManager
- func (tm *TemplateManager) ExcludeDirectory(directory string) *TemplateManager
- func (tm *TemplateManager) MissingKey(option string) *TemplateManager
- func (tm *TemplateManager) OverloadFunctions() *TemplateManager
- func (tm *TemplateManager) Parse() error
- func (tm *TemplateManager) Reload(reload bool) *TemplateManager
- func (tm *TemplateManager) RemoveAllFunctions() *TemplateManager
- func (tm *TemplateManager) RemoveComponentDirectories(directories []string) *TemplateManager
- func (tm *TemplateManager) RemoveComponentDirectory(directory string) *TemplateManager
- func (tm *TemplateManager) RemoveExcludedDirectory(directory string) *TemplateManager
- func (tm *TemplateManager) RemoveFunction(name string) *TemplateManager
- func (tm *TemplateManager) RemoveFunctions(names []string) *TemplateManager
- func (tm *TemplateManager) RemoveOverloadFunctions() *TemplateManager
- func (tm *TemplateManager) RenameFunction(current string, new string) *TemplateManager
- func (tm *TemplateManager) RenameFunctions(functions map[string]string) *TemplateManager
- func (tm *TemplateManager) Render(name string, params Params, writer io.Writer) error
- func (tm *TemplateManager) TemplateEngine(engine string) *TemplateManager
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetConsoleErrors ¶ added in v0.1.0
func SetConsoleErrors(errors bool)
Control whether errors are written to the console
func SetConsoleWarnings ¶ added in v0.1.0
func SetConsoleWarnings(warnings bool)
Control whether warnings are written to the console
func SetDefaultDateFormat ¶ added in v0.0.5
func SetDefaultDateFormat(format string)
Sets the default format for the `date` function (default: d/m/Y) May be in Go, PHP or Python format
func SetDefaultDatetimeFormat ¶ added in v0.0.5
func SetDefaultDatetimeFormat(format string)
Sets the default format for the `datetime` function (default: d/m/Y H:i) May be in Go, PHP or Python format
func SetDefaultTimeFormat ¶ added in v0.0.5
func SetDefaultTimeFormat(format string)
Sets the default format for the `time` function (default: H:i) May be in Go, PHP or Python format
func SetHaltOnErrors ¶ added in v0.1.0
func SetHaltOnErrors(errors bool)
Control whether errors are written to the log
func SetHaltOnWarnings ¶ added in v0.1.0
func SetHaltOnWarnings(warnings bool)
Control whether warnings are written to the log
func SetTimezoneFixed ¶
Sets the default timezone location used by date / time functions to a fixed offset (default: UTC)
func SetTimezoneLocation ¶
Sets the default timezone location used by date / time functions (default: UTC)
func SetTimezoneLocationString ¶
Sets the default timezone location used by date / time functions from a string (default: UTC)
Types ¶
type Template ¶ added in v0.1.1
type Template struct {
// contains filtered or unexported fields
}
Allows the use of either HTML or Text template packages
func NewHtmlTemplate ¶ added in v0.1.1
func NewTemplate ¶ added in v0.1.1
func NewTextTemplate ¶ added in v0.1.1
func (*Template) ExecuteTemplate ¶ added in v0.1.1
func (*Template) NewSubTemplate ¶ added in v0.1.1
type TemplateManager ¶
type TemplateManager struct {
// contains filtered or unexported fields
}
Holds all templates and variables along with all required settings
func AutomaticInit ¶
func AutomaticInit() (*TemplateManager, error)
Attempts to automatically configure a `TemplateManager` instance
func Init ¶
func Init(directory string, extensions ...string) *TemplateManager
Creates a new `TemplateManager` struct instance
func InitEmbed ¶ added in v0.0.7
func InitEmbed(fileSystem embed.FS, directory string, extensions ...string) *TemplateManager
Creates a new `TemplateManager` struct instance using an embedded filesystem
func (*TemplateManager) AddComponentDirectories ¶ added in v0.0.11
func (tm *TemplateManager) AddComponentDirectories(directories []string) *TemplateManager
Adds multiple directories that contain components. (Must be within the templates directory)
func (*TemplateManager) AddComponentDirectory ¶ added in v0.0.11
func (tm *TemplateManager) AddComponentDirectory(directory string) *TemplateManager
Adds a directory that contains components. (Must be within the templates directory)
func (*TemplateManager) AddFunction ¶
func (tm *TemplateManager) AddFunction(name string, function any) *TemplateManager
Adds a custom function for use in all templates within the instance of `TemplateManager`
func (*TemplateManager) AddFunctions ¶
func (tm *TemplateManager) AddFunctions(functions map[string]any) *TemplateManager
Adds multiple custom functions for use in all templates within the instance of `TemplateManager` Function names are the map keys.
func (*TemplateManager) AddParam ¶
func (tm *TemplateManager) AddParam(templateName string, name string, value any) *TemplateManager
Adds a single variable (`name`) with value `value` that will always be available in the `templateName` template
func (*TemplateManager) AddParams ¶
func (tm *TemplateManager) AddParams(templateName string, params Params) *TemplateManager
Adds several variables (`params`) that will always be available in the `templateName` template
func (*TemplateManager) Debug ¶
func (tm *TemplateManager) Debug(debug bool) *TemplateManager
Enable debugging of the template build process
func (*TemplateManager) Delimiters ¶
func (tm *TemplateManager) Delimiters(left string, right string) *TemplateManager
Sets the delimiters used by `text/template` (Default: "{{" and "}}")
func (*TemplateManager) ExcludeDirectories ¶
func (tm *TemplateManager) ExcludeDirectories(directories []string) *TemplateManager
Excludes multiple directories from the build scanning process (which only wants entry files). This does not prevent files in these directories from being included via `template`. Typically, directories containing base layouts and partials should be excluded.
func (*TemplateManager) ExcludeDirectory ¶
func (tm *TemplateManager) ExcludeDirectory(directory string) *TemplateManager
Exclude a directory from the build scanning process (which only wants entry files). This does not prevent files in this directory from being included via `template`. Typically, directories containing base layouts and partials should be excluded.
func (*TemplateManager) MissingKey ¶ added in v0.1.4
func (tm *TemplateManager) MissingKey(option string) *TemplateManager
Allows the `text/template` Option `missingkey` to be customised. This setting controls what happens when an unset value is printed (i.e. {{ .Unset }}). Valid Options: "default", "invalid" (output: "<no value>"), "zero" (output: "") or "error" (halts execution)
func (*TemplateManager) OverloadFunctions ¶ added in v0.0.10
func (tm *TemplateManager) OverloadFunctions() *TemplateManager
Replaces standard `text/template` functions with the `TemplateManager` alternatives
func (*TemplateManager) Parse ¶
func (tm *TemplateManager) Parse() error
Triggers scanning of files and bundling of all templates
func (*TemplateManager) Reload ¶
func (tm *TemplateManager) Reload(reload bool) *TemplateManager
Enable re-rebuilding of the template bundle upon every page load (for development)
func (*TemplateManager) RemoveAllFunctions ¶
func (tm *TemplateManager) RemoveAllFunctions() *TemplateManager
Removes all functions currently assigned to the instance of `TemplateManager`. Useful if you do not want the default functions included
func (*TemplateManager) RemoveComponentDirectories ¶ added in v0.0.11
func (tm *TemplateManager) RemoveComponentDirectories(directories []string) *TemplateManager
Removes multiple directories that contain components from component parsing.
func (*TemplateManager) RemoveComponentDirectory ¶ added in v0.0.11
func (tm *TemplateManager) RemoveComponentDirectory(directory string) *TemplateManager
Removes a directory that contains components from component parsing.
func (*TemplateManager) RemoveExcludedDirectory ¶
func (tm *TemplateManager) RemoveExcludedDirectory(directory string) *TemplateManager
Removes a directory that was previously excluded to allow it to feature in the build scanning process (which only wants entry files).
func (*TemplateManager) RemoveFunction ¶ added in v0.0.10
func (tm *TemplateManager) RemoveFunction(name string) *TemplateManager
Removes the function named (does not affect built-in `template/text` functions)
func (*TemplateManager) RemoveFunctions ¶ added in v0.0.10
func (tm *TemplateManager) RemoveFunctions(names []string) *TemplateManager
Removes the functions named (does not affect built-in `template/text` functions)
func (*TemplateManager) RemoveOverloadFunctions ¶ added in v0.0.10
func (tm *TemplateManager) RemoveOverloadFunctions() *TemplateManager
Replaces standard `text/template` functions with the `TemplateManager` alternatives
func (*TemplateManager) RenameFunction ¶ added in v0.1.3
func (tm *TemplateManager) RenameFunction(current string, new string) *TemplateManager
Allows any `TemplateManager` function to be renamed
func (*TemplateManager) RenameFunctions ¶ added in v0.1.3
func (tm *TemplateManager) RenameFunctions(functions map[string]string) *TemplateManager
Allows multiple `TemplateManager` functions to be renamed at once
func (*TemplateManager) TemplateEngine ¶ added in v0.1.1
func (tm *TemplateManager) TemplateEngine(engine string) *TemplateManager
Sets whether `TemplateManager` should use the `text/template` package or the `html/template` package