pages

README

Overview

A super lightweight template engine to load and parse go templates from the local filesystem. It works with gin out of the box.

To install it:

go install github.com/gsuntres/pages

Usage

Pages was designed to work with gin's HTMLRender.

engine := gin.New()

instance := pages.NewPagesWithProps(&pages.PagesProps{
  Mode: ModeLocal,
})

engine.HTMLRender = instance

By default, Pages will look for template files in the pages directory. To render a template you call

c.HTML(200, "mypage.html")

or

c.HTML(200, "subpath/mypage.html")

when paths are relative to pages.

To render pages using a layout

c.HTML(200, "subpath/mypage.html?layout=layout.html")

Pages will make sure to load layout.html first then mypage.html and render the final template.

Cache

By default caching is disabled. Any changes on the templates will show up on the next render.

To enable it, pass WithCache = true to PagesProps.

Helper Functions

Gotemplate's equivalent to locals in express.js is template.FuncMap. Pages has the following functions availabe in templates:

• safe: to escape html
• safeURL: to escape url strings
• json: to parse data into json
• jsonPretty: same as json but more redable json
• ifelse: a convenient one line if else statement
• call: safely calls a function if it exists

To add more

instance.AddFunc(name, func)

Documentation

Index

• Constants
• func Bootstrap(r *gin.Engine, group *PageGroup)
• func ParentLayout(group *PageGroup) string
• type Mode
• type Page
  • func (page *Page) AbsPath() string
  • func (page *Page) FullPath() string
  • func (page *Page) GetParams() []string
  • func (page *Page) GetPath() string
  • func (page *Page) HasLayout() bool
  • func (page *Page) HasParams() bool
  • func (page *Page) Layout() string
• type PageGroup
  • func PageParse(dir string) (*PageGroup, error)
  • func PageParseWithParent(dir string, parent *PageGroup) (*PageGroup, error)
  • func (pg *PageGroup) FullPath() string
  • func (pg *PageGroup) GetLayout() string
  • func (pg *PageGroup) HasIndex() bool
  • func (pg *PageGroup) HasLayout() bool
  • func (pg *PageGroup) IsRoot() bool
• type Pages
  • func NewPages() *Pages
  • func NewPagesWithProps(props *PagesProps) *Pages
  • func (p *Pages) AddFunc(name string, fn any)
  • func (r *Pages) AddTemplate(name string, filenames ...string) error
  • func (p *Pages) AddTemplatesFromGroup(group *PageGroup) error
  • func (p *Pages) BootstrapGin(ginEngin *gin.Engine, group *PageGroup)
  • func (p *Pages) Count() int
  • func (p *Pages) GetFuncMap() template.FuncMap
  • func (p *Pages) Init(props *PagesProps) error
  • func (p *Pages) Instance(name string, data any) render.Render
  • func (p *Pages) LoadDefault(root *template.Template, path string) *template.Template
  • func (p *Pages) LoadLocal(root *template.Template, filenames ...string) *template.Template
• type PagesProps

Constants

const (
	ModeDefault = iota
	ModeLocal
	ModeS3
)

Functions

func Bootstrap

func Bootstrap(r *gin.Engine, group *PageGroup)

Bootstrap configures gin router according to a tree of PageGroups The next step is to configure gin.Engine renderer using Pages.

func ParentLayout

func ParentLayout(group *PageGroup) string

Types

type Mode

type Mode int

type Page

type Page struct {
	Group    *PageGroup
	Name     string
	Path     string
	Filename string
}

Page holds information required to render the final page and route

func (*Page) AbsPath

func (page *Page) AbsPath() string

func (*Page) FullPath

func (page *Page) FullPath() string

func (*Page) GetParams

func (page *Page) GetParams() []string

func (*Page) GetPath

func (page *Page) GetPath() string

func (*Page) HasLayout

func (page *Page) HasLayout() bool

func (*Page) HasParams

func (page *Page) HasParams() bool

func (*Page) Layout

func (page *Page) Layout() string

type PageGroup

type PageGroup struct {
	Dir    string
	Index  string
	Layout string
	Path   string
	Pages  []*Page
	Parent *PageGroup
	Groups []*PageGroup
}

PageGroup provides a general view of the directory where templates and other directories exist.

func PageParse

func PageParse(dir string) (*PageGroup, error)

func PageParseWithParent

func PageParseWithParent(dir string, parent *PageGroup) (*PageGroup, error)

func (*PageGroup) FullPath

func (pg *PageGroup) FullPath() string

func (*PageGroup) GetLayout

func (pg *PageGroup) GetLayout() string

func (*PageGroup) HasIndex

func (pg *PageGroup) HasIndex() bool

func (*PageGroup) HasLayout

func (pg *PageGroup) HasLayout() bool

func (*PageGroup) IsRoot

func (pg *PageGroup) IsRoot() bool

type Pages

type Pages struct {
	Mode Mode

	WithCache bool

	Root *PageGroup

	// Pages directory where templates are located (default: pages)
	Pages string
	// contains filtered or unexported fields
}

Pages is the root instance

func NewPages

func NewPages() *Pages

func NewPagesWithProps

func NewPagesWithProps(props *PagesProps) *Pages

func (*Pages) AddFunc

func (p *Pages) AddFunc(name string, fn any)

func (*Pages) AddTemplate

func (r *Pages) AddTemplate(name string, filenames ...string) error

func (*Pages) AddTemplatesFromGroup

func (p *Pages) AddTemplatesFromGroup(group *PageGroup) error

func (*Pages) BootstrapGin

func (p *Pages) BootstrapGin(ginEngin *gin.Engine, group *PageGroup)

func (*Pages) Count

func (p *Pages) Count() int

Count the number templates

func (*Pages) GetFuncMap

func (p *Pages) GetFuncMap() template.FuncMap

func (*Pages) Init

func (p *Pages) Init(props *PagesProps) error

func (*Pages) Instance

func (p *Pages) Instance(name string, data any) render.Render

func (*Pages) LoadDefault

func (p *Pages) LoadDefault(root *template.Template, path string) *template.Template

func (*Pages) LoadLocal

func (p *Pages) LoadLocal(root *template.Template, filenames ...string) *template.Template

type PagesProps

type PagesProps struct {
	Mode      Mode
	WithCache bool
	Pages     string
}