templates

README

templates

What is it about?

1. allows you to have layouts, pages, blocks (partials)
2. allows you to live reload public files and templates in dev mode and use embeded files in production (golang's embed)
3. allows you to render dynamically set blocks via 'd-block' instead of 'block'
4. d-block allows you to use a headless-cms that serves json and assets only

Usage with echo (not needed):

1. Create directories and files:

• files
  • public
    • override.css
    • hopefullynot.js
  • templates
    • layouts
      • application.gohtml
      • special.gohtml
    • pages (must contain define 'page' - all of em, always 'page' - not 'todos_show' etc.)
      • todos_show.gohtml
      • todos_index.gohtml
      • todos_edit.gohtml
      • ...
    • blocks (definition within file must start with _ and must contain definition '_form')
      • form.gohtml
      • message.gohtml

2. Initialize:

    import echo_integration "github.com/templates/integrations/echo"

    ...


	// (embeded) public files and templates
	fileSystem := getFileSystem("files", in_dev_mode)
	templates := templates.New(fileSystem, "./templates", nil)
	templates.AlwaysReloadAndParseTemplates = in_dev_mode
	templates.MustParseTemplates()

	// sample echo
	e := echo.New()
	e.Pre(echo_integration.MethodOverrideFormField("_method"))
	e.Use(echo_integration.CSRFTokenLookup("form:csrf"))
	e.Use(middleware.Logger())
	e.Use(middleware.Recover())
	e.Renderer = echo_integration.Renderer(templates)

3. Use in handler

func (ht *Handlers) Todos(c echo.Context) error {
	...
	return c.Render(200, "todos_index", data) // renders page with default layout 'application'
    // or
    return c.Render(200, "special:todos_index", data) // renders the page with the 'special' layout
    // or
    return c.Render(200, ":todos_index", data) // renders the page without a layout 
    // or
    return c.Render(200, "_message", data) // renders only the block/partial/snippet/... without a page or layout

    // without echo
   templates.ExecuteTemplate(respone, request, "_message or as above", data)
}

Locals can be passed to blocks

{{block "_sample_block_with_locals" locals "a" 1 "b" 2 "c" 3  }}{{end}}
{{locals "a" "x" "b" "y" "c" "z" | d_block "_sample_block_with_locals"   }}

Todos till v0.1.0

[x] use safehtml instead of std lib [x] move integrations_echo to seperate package [ ] code cleanup [ ] implement sse for hotwired turbo [ ] add tests for hotwired turbo

Documentation

Index

• func Locals(args ...any) map[string]any
• type LayoutContextKey
• type Templates
  • func New(efs *embed.FS, fnMap template.FuncMap) *Templates
  • func (t *Templates) AddDynamicBlockToFuncMap()
  • func (t *Templates) AddFuncMapHelpers()
  • func (t *Templates) AddLocalsToFuncMap()
  • func (t *Templates) AddTrustedHTMLToFuncMap()
  • func (t *Templates) ExecuteTemplate(w io.Writer, r *http.Request, templateName string, data interface{}) error
  • func (t *Templates) ExecuteTemplateAsText(r *http.Request, templateName string, data interface{}) (string, error)
  • func (t *Templates) GetParsedTemplates() []string
  • func (t *Templates) HandlerRenderWithData(templateName string, data interface{}) func(w http.ResponseWriter, r *http.Request)
  • func (t *Templates) HandlerRenderWithDataFromContext(templateName string, contextKey interface{}) func(w http.ResponseWriter, r *http.Request)
  • func (t *Templates) MustParseTemplates()
  • func (t *Templates) ParseTemplates() error
  • func (t *Templates) RenderBlockAsHTMLString(blockname string, payload interface{}) (safehtml.HTML, error)

Functions

func Locals

func Locals(args ...any) map[string]any

Types

type LayoutContextKey

type LayoutContextKey struct{}

LayoutContextKey is the key for getting the layout string out of the context

type Templates

type Templates struct {
	AlwaysReloadAndParseTemplates bool

	DefaultLayout         string
	TemplateFileExtension string

	TemplatesPath template.TrustedSource
	LayoutsPath   string
	PagesPath     string
	BlocksPath    string

	AddHeadlessCMSFuncMapHelpers bool
	// contains filtered or unexported fields
}

func New

func New(efs *embed.FS, fnMap template.FuncMap) *Templates

New return new Templates with default configs and templates functions to support headless cms

func (*Templates) AddDynamicBlockToFuncMap

func (t *Templates) AddDynamicBlockToFuncMap()

AddDynamicBlockToFuncMap adds 'd_block' to the FuncMap which allows to render blocks from variables dynamically set Rob doesn't like, we add it anyway because we like headless cms https://stackoverflow.com/questions/28830543/how-to-use-a-field-of-struct-or-variable-value-as-template-name

func (*Templates) AddFuncMapHelpers

func (t *Templates) AddFuncMapHelpers()

func (*Templates) AddLocalsToFuncMap

func (t *Templates) AddLocalsToFuncMap()

func (*Templates) AddTrustedHTMLToFuncMap

func (t *Templates) AddTrustedHTMLToFuncMap()

func (*Templates) ExecuteTemplate

func (t *Templates) ExecuteTemplate(w io.Writer, r *http.Request, templateName string, data interface{}) error

ExecuteTemplate renders the template specified by name (layout:page or just page)

func (*Templates) ExecuteTemplateAsText

func (t *Templates) ExecuteTemplateAsText(r *http.Request, templateName string, data interface{}) (string, error)

func (*Templates) GetParsedTemplates

func (t *Templates) GetParsedTemplates() []string

func (*Templates) HandlerRenderWithData

func (t *Templates) HandlerRenderWithData(templateName string, data interface{}) func(w http.ResponseWriter, r *http.Request)

HandlerRenderWithData returns a Handler function which only renders the template

func (*Templates) HandlerRenderWithDataFromContext

func (t *Templates) HandlerRenderWithDataFromContext(templateName string, contextKey interface{}) func(w http.ResponseWriter, r *http.Request)

HandlerRenderWithDataFromContext returns a Handler function which only renders the template and uses data from context

func (*Templates) MustParseTemplates

func (t *Templates) MustParseTemplates()

MustParseTemplates goes fatal if there is an error

func (*Templates) ParseTemplates

func (t *Templates) ParseTemplates() error

ParseTemplates reads all html files and freshly compiles the templates

func (*Templates) RenderBlockAsHTMLString

func (t *Templates) RenderBlockAsHTMLString(blockname string, payload interface{}) (safehtml.HTML, error)

RenderBlockAsHTMLString renders a template from the templates-map as a HTML-String