manager

README

Gin template manager

Manages Golang templates and integrates with Gin framework.

Features:

• Layouts, including nested ('base', 'sub-base', 'sub-sub-base', ...)
• Caching
• Streaming
• Supports embedded assets
• Supports named routes with parameters (ex: .Ref "eventByID" 1234 could be mapped to ../events/1234 with proper escaping)

Check example directory.

The project is focusing on developer experience (DX) rather on the performance.

Goals are:

• make developing SSR applications on Go convenient and simple
• extend and integrate (not replace) with Gin framework
• keep it flexible

Inspirations: Hugo, Django, Rails

STATUS: proof-of-concept

Usage

Initialize manager

• Opt: filesystem: templates := mananger.New(os.DirFS("path-to-dir"))
• Opt: assets (embedded): templates := mananger.New(assets)

Link to Gin router

• router.HTMLRender = templates

Render

• gctx.HTML(http.StatusOK, "index.html", "params")

Example

templates := mananger.New(os.DirFS("path-to-dir"))

router := gin.Default()
router.HTMLRender = templates

router.GET("/", func(gctx *gin.Context) {
    gctx.HTML(http.StatusOK, "index.html", "params")
})
// ...

Convention

Directory structure

• @layout.html - layout file

Documentation

Index

• Constants
• func Rel(gctx *gin.Context, paths ...string) string
• type Links
  • func NewLinks(engine *gin.Engine) *Links
  • func (mgr *Links) Named(name string, path string) string
  • func (mgr *Links) Path(alias string, args ...interface{}) (string, error)
• type Manager
  • func New(fs fs.FS, options ...Option) *Manager
  • func (mgr *Manager) Alias(aliasName, templateFile string)
  • func (mgr *Manager) Compile() error
  • func (mgr *Manager) Get(name string) (*template.Template, error)
  • func (mgr *Manager) Instance(name string, params interface{}) render.Render
• type Option
  • func Cache() Option
  • func Func(name string, fn interface{}) Option
  • func FuncMap(functions template.FuncMap) Option
  • func Stream() Option
• type ViewContext
  • func View(gctx *gin.Context, userData interface{}) *ViewContext
  • func (vc *ViewContext) Context() *gin.Context
  • func (vc *ViewContext) Data() interface{}
  • func (vc *ViewContext) In(href string) bool
  • func (vc *ViewContext) Path() string
  • func (vc *ViewContext) Ref(alias string, args ...interface{}) (string, error)
  • func (vc *ViewContext) Rel(values ...interface{}) string
  • func (vc *ViewContext) RelArgs(href string, paths []string) string

Constants

const LayoutFile = "@layout.html"

Functions

func Rel

func Rel(gctx *gin.Context, paths ...string) string

Rel constructs relative path for provided absolute path.

Types

type Links

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

func NewLinks

func NewLinks(engine *gin.Engine) *Links

NewLinks creates and installs alias handler.

func (*Links) Named

func (mgr *Links) Named(name string, path string) string

Named registers route under provided name, which could be used in Views by .Ref function. Example:

gin.GET(links.Named("eventByID", "/event/:id"), func(gctx *gin.Context) {
})
...

Then in view we can use

{{.Ref "eventByID" 1234}}

Which will generate relative URL to named route with proper parameters

func (*Links) Path

func (mgr *Links) Path(alias string, args ...interface{}) (string, error)

Path to alias with arguments (escaped).

type Manager

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

Manager of templates. Supports caching (builds template once), streaming (render directly to client), and functions map (ex: Sprig).

func New

func New(fs fs.FS, options ...Option) *Manager

New template manager which supports layouts and can be used as template engine for Gin.

func (*Manager) Alias

func (mgr *Manager) Alias(aliasName, templateFile string)

Alias template file (related to FS used during creation) and to short name. Thread UNSAFE, since templates are usually supposed to be added once during the initialization phase.

func (*Manager) Compile

func (mgr *Manager) Compile() error

Compile all templates. There is no sense to use it without enabled caching. Could be used as warm-up.

func (*Manager) Get

func (mgr *Manager) Get(name string) (*template.Template, error)

Get and parse template (optionally from cache) by the template name or alias. If cache enabled, template will be compiled only once. Thread-safe.

func (*Manager) Instance

func (mgr *Manager) Instance(name string, params interface{}) render.Render

Instance of Gin renderer, used by Gin itself.

type Option

type Option func(mgr *Manager)

func Cache

func Cache() Option

Cache compiled template. Slightly increases memory usage. Recommended in production environment.

func Func

func Func(name string, fn interface{}) Option

Func adds templates functions to internal map.

func FuncMap

func FuncMap(functions template.FuncMap) Option

FuncMap sets user-defined functions for templates. For example: Sprig library.

func Stream

func Stream() Option

Stream response directly to client. Reduces memory consumption, but it will not let system send valid 5xx code in case of rendering failure.

type ViewContext

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

ViewContext is convenient wrapper around context and data which could be used in templates.

func View

func View(gctx *gin.Context, userData interface{}) *ViewContext

View creates view context which could be used in template. Provides useful methods and exposes user data via .Data method.

func (*ViewContext) Context

func (vc *ViewContext) Context() *gin.Context

Context used by handler.

func (*ViewContext) Data

func (vc *ViewContext) Data() interface{}

Data provided by user

func (*ViewContext) In

func (vc *ViewContext) In(href string) bool

In checks is current path equal or under provided href.

func (*ViewContext) Path

func (vc *ViewContext) Path() string

Path from request.

func (*ViewContext) Ref

func (vc *ViewContext) Ref(alias string, args ...interface{}) (string, error)

Ref creates relative path to alias with args if required. Requires Links to be installed.

func (*ViewContext) Rel

func (vc *ViewContext) Rel(values ...interface{}) string

Rel constructs relative path from absolute.

func (*ViewContext) RelArgs

func (vc *ViewContext) RelArgs(href string, paths []string) string

RelArgs constructs relative path from absolute and provided path parts.