README
¶
htempl
Each .htempl file contains a yaml fragment with variable definitions. A few variables have a special meaning:
- include: include yaml from the named file.
- includes: include the yaml from all of the named files.
- template: Include templates from the named file.
- templates: Include the template from all of the named files.
All variables are available as "." variables while executing the template.
The remainder of the file after the yaml block is appended to the other templates to build the final template. See the package documentation for more details on how to use the library:
https://pkg.go.dev/github.com/jum/htempl
The utility htempl in cmd/htempl can be used to statically generate HTML pages from templates as a kind of static site generator.
Example:
---
title: This is a Test
template: site.templ
...
{{.title}}
template text appended to site.templ and executed with the yaml data as dot.
{{template "site" .}}
There are a few special functions in the FuncMap of the template that can be used:
- safeattr(string) convert string into a HTML attribute for dynamically constructing HTML attributes.
- safehtml(sring) convert string to HTML that is not escaped by the default html/template escaping.
- safejs(string) convert string to javascript that is not escaped.
- safecss(string) convert string to css that is not escaped.
- safeurl(string) convert string to an url that is not escaped.
- md2html(string) convert string in markdown syntax into HTML using the gomarkdown markdown parser.
- withDefault(m map[string]interface{}, key string, value interface{}) returns the map making sure that the key key is present with the given value as a default.
- map(args...) args must be an even numbered key and value pairs, map returns the constructed map.
A recent talk on htempl for the Hannover golang meeting in the subdirectory slides. To view the slides online: https://go-talks.appspot.com/github.com/jum/htempl/slides/htempl.slide
Documentation
¶
Overview ¶
Package htempl combines go html/templates with YAML configuration in one file. The constants yamlStart and yamlEnd delimit the YAML header in front of the go template section:
---
hello: "world"
...
{{.hello}}
Predefined YAML values ¶
The predefined YAML values are all expected to be filenames that are to be included in the final htmpl document.
include The named file is included in the YAML section to define more YAML data elements. includes The list of named files is included in the YAML section to define more YAML data elements. template The named file is included in the go template section for more template data. templates The list of named files is included in the go template section for more template data.
Functions ¶
The variable DefaultTemplateFunc is the default FuncMap that is installed and supports the following template functions:
map The arguments are expected to be pairs of names and interfaces and are returned as a new map. withDefault The first argument is a map, and the second a name and the third an interfae. The returned map makes sure the name and interface are present in the output map in case the input map does not have a value for name. md2html Returns the result of converting the argument from Markdown to HTML. safeattr Returns the argument as an template.HTMLAttr to avoid escaping in HTML attribute argumentsq. safehtml Returns the argument as template.HTML to avoid HTML escaping. safejs Returns the argument as template.JS to avoid javascript escaping. safecss Returns the argument as template.CSS to avoid CSS escaping. safeurl Returns the argument as template.URL to avoid URL escaping.
Index ¶
- Variables
- type HTempl
- func New(fname string) (*HTempl, error)
- func NewReader(tmplName string, in io.Reader) (*HTempl, error)
- func NewString(tmplName string, tmplString string) (*HTempl, error)
- func NewWithTemplFuncs(fname string, funcMap template.FuncMap) (*HTempl, error)
- func NewWithTemplFuncsReader(tmplName string, in io.Reader, funcMap template.FuncMap) (*HTempl, error)
Constants ¶
This section is empty.
Variables ¶
var DefaultTemplFuncs template.FuncMap = template.FuncMap{ "map": func(args ...interface{}) (map[string]interface{}, error) { if len(args)&1 == 1 { return nil, fmt.Errorf("map: number of args must be even") } val := make(map[string]interface{}) for i := 0; i < len(args); i += 2 { val[args[i].(string)] = args[i+1] } return val, nil }, "withDefault": func(m map[string]interface{}, key string, value interface{}) map[string]interface{} { if len(key) == 0 || value == nil { return m } nm := make(map[string]interface{}) nm[key] = value for k, v := range m { nm[k] = v } return nm }, "md2html": func(value string) template.HTML { return template.HTML(markdown.ToHTML([]byte(value), nil, nil)) }, "safeattr": func(value string) template.HTMLAttr { return template.HTMLAttr(value) }, "safehtml": func(value string) template.HTML { return template.HTML(value) }, "safejs": func(value string) template.JS { return template.JS(value) }, "safecss": func(value string) template.CSS { return template.CSS(value) }, "safeurl": func(value string) template.URL { return template.URL(value) }, }
DefaultTemplFuncs are the default function mapping for New.
Functions ¶
This section is empty.
Types ¶
type HTempl ¶
HTempl denotes a template combined by variables from a leading YAML block. The variable names "include", "includes", "template" and "templates" are special
func NewReader ¶ added in v0.5.0
NewReader parses a YAML/template combination using the default FuncMap and the given io.Reader
func NewString ¶ added in v0.5.0
NewString parses a YAML/template string combination using the default FuncMap
func NewWithTemplFuncs ¶
NewWithTemplFuncs parses a YAML/template file combination using the given FuncMap
Source Files
Directories