template

README

---

title: 👋 Welcome description: 🧬 Template engine middlewares for Fiber. sidebar_position: 1

This package provides universal methods to use multiple template engines with the Fiber web framework using the new Views interface that is available from > v1.11.1. Special thanks to @bdtomlin & @arsmn for helping!

9 template engines are supported:

• ace
• amber
• django
• handlebars
• html
• jet
• mustache
• pug
• slim

Installation

Go version 1.17 or higher is required.

go get -u github.com/gofiber/fiber/v2
go get -u github.com/gofiber/template/any_template_engine/vX

Example

package main

import (
	"log"

	"github.com/gofiber/fiber/v2"

	// To use a specific template engine, import as shown below:
	// "github.com/gofiber/template/pug"
	// "github.com/gofiber/template/mustache"
	// etc..

	// In this example we use the html template engine
	"github.com/gofiber/template/html/v2"
)

func main() {
	// Create a new engine by passing the template folder
	// and template extension using <engine>.New(dir, ext string)
	engine := html.New("./views", ".html")

  	// We also support the http.FileSystem interface
	// See examples below to load templates from embedded files
	engine := html.NewFileSystem(http.Dir("./views"), ".html")

	// Reload the templates on each render, good for development
	engine.Reload(true) // Optional. Default: false

	// Debug will print each template that is parsed, good for debugging
	engine.Debug(true) // Optional. Default: false

	// Layout defines the variable name that is used to yield templates within layouts
	engine.Layout("embed") // Optional. Default: "embed"

	// Delims sets the action delimiters to the specified strings
	engine.Delims("{{", "}}") // Optional. Default: engine delimiters

	// AddFunc adds a function to the template's global function map.
	engine.AddFunc("greet", func(name string) string {
		return "Hello, " + name + "!"
	})

	// After you created your engine, you can pass it to Fiber's Views Engine
	app := fiber.New(fiber.Config{
		Views: engine,
	})

	// To render a template, you can call the ctx.Render function
	// Render(tmpl string, values interface{}, layout ...string)
	app.Get("/", func(c *fiber.Ctx) error {
		return c.Render("index", fiber.Map{
			"Title": "Hello, World!",
		})
	})

	// Render with layout example
	app.Get("/layout", func(c *fiber.Ctx) error {
		return c.Render("index", fiber.Map{
			"Title": "Hello, World!",
		}, "layouts/main")
	})

	log.Fatal(app.Listen(":3000"))
}

More Examples

To view more specific examples, you could visit each engine folder to learn more

• ace
• amber
• django
• handlebars
• html
• jet
• mustache
• pug
• slim

embedded Systems

We support the http.FileSystem interface, so you can use different libraries to load the templates from embedded binaries.

pkger

Read documentation: https://github.com/markbates/pkger

package main

import (
	"log"

	"github.com/gofiber/fiber/v2"
	"github.com/gofiber/template/html"

	"github.com/markbates/pkger"
)

func main() {
	engine := html.NewFileSystem(pkger.Dir("/views"), ".html")

	app := fiber.New(fiber.Config{
		Views: engine,
	})

	// run pkger && go build
}

packr

Read documentation: https://github.com/gobuffalo/packr

package main

import (
	"log"

	"github.com/gofiber/fiber/v2"
	"github.com/gofiber/template/html"

	"github.com/gobuffalo/packr/v2"
)

func main() {
	engine := html.NewFileSystem(packr.New("Templates", "/views"), ".html")

	app := fiber.New(fiber.Config{
		Views: engine,
	})

	// run packr && go build
}

go.rice

Read documentation: https://github.com/GeertJohan/go.rice

package main

import (
	"log"

	"github.com/gofiber/fiber/v2"
	"github.com/gofiber/template/html"

	"github.com/GeertJohan/go.rice"
)

func main() {
	engine := html.NewFileSystem(rice.MustFindBox("views").HTTPBox(), ".html")

	app := fiber.New(fiber.Config{
		Views: engine,
	})

	// run rice embed-go && go build
}

fileb0x

Read documentation: https://github.com/UnnoTed/fileb0x

package main

import (
	"log"

	"github.com/gofiber/fiber/v2"
	"github.com/gofiber/template/html"
	// your generated package
	"github.com/<user>/<repo>/static"
)

func main() {
	engine := html.NewFileSystem(static.HTTP, ".html")

	app := fiber.New(fiber.Config{
		Views: engine,
	})

	// Read the documentation on how to use fileb0x
}

Benchmarks

Simple

Extended

Benchmarks were ran on Apple Macbook M1. Each engine was benchmarked 20 times and the results averaged into a single xlsx file. Mustache was excluded from the extended benchmark

Documentation

Index

• type Engine
  • func (e *Engine) AddFunc(name string, fn interface{}) IEngineCore
  • func (e *Engine) AddFuncMap(m map[string]interface{}) IEngineCore
  • func (e *Engine) Debug(enabled bool) IEngineCore
  • func (e *Engine) Delims(left, right string) IEngineCore
  • func (e *Engine) FuncMap() map[string]interface{}
  • func (e *Engine) Layout(key string) IEngineCore
  • func (e *Engine) PreRenderCheck() bool
  • func (e *Engine) Reload(enabled bool) IEngineCore
• type IEngine
• type IEngineCore

Types

type Engine

type Engine struct {
	IEngineCore
	// delimiters
	Left  string
	Right string
	// views folder
	Directory string
	// http.FileSystem supports embedded files
	FileSystem http.FileSystem
	// views extension
	Extension string
	// layout variable name that incapsulates the template
	LayoutName string
	// determines if the engine parsed all templates
	Loaded bool
	// reload on each render
	ShouldReload bool
	// debug prints the parsed templates
	Verbose bool
	// lock for funcmap and templates
	Mutex sync.RWMutex
	// template funcmap
	Funcmap map[string]interface{}
}

Engine engine struct

func (*Engine) AddFunc

func (e *Engine) AddFunc(name string, fn interface{}) IEngineCore

AddFunc adds the function to the template's function map. It is legal to overwrite elements of the default actions

func (*Engine) AddFuncMap

func (e *Engine) AddFuncMap(m map[string]interface{}) IEngineCore

AddFuncMap adds the functions from a map to the template's function map. It is legal to overwrite elements of the default actions

func (*Engine) Debug

func (e *Engine) Debug(enabled bool) IEngineCore

Debug will print the parsed templates when Load is triggered.

func (*Engine) Delims

func (e *Engine) Delims(left, right string) IEngineCore

Delims sets the action delimiters to the specified strings, to be used in templates. An empty delimiter stands for the corresponding default: "{{" and "}}".

func (*Engine) FuncMap

func (e *Engine) FuncMap() map[string]interface{}

FuncMap returns the template's function map.

func (*Engine) Layout

func (e *Engine) Layout(key string) IEngineCore

Layout defines the variable name that will incapsulate the template

func (*Engine) PreRenderCheck

func (e *Engine) PreRenderCheck() bool

Check if the engine should reload the templates before rendering Explicit Mute Unlock vs defer offers better performance

func (*Engine) Reload

func (e *Engine) Reload(enabled bool) IEngineCore

Reload if set to true the templates are reloading on each render, use it when you're in development and you don't want to restart the application when you edit a template file.

type IEngine

type IEngine interface {
	IEngineCore
	Load() error
	Render(out io.Writer, template string, binding interface{}, layout ...string) error
}

IEngine interface, to be implemented for any templating engine added to the repository

type IEngineCore

type IEngineCore interface {
	AddFunc(name string, fn interface{}) IEngineCore
	AddFuncMap(m map[string]interface{}) IEngineCore
	Debug(enabled bool) IEngineCore
	Delims(left, right string) IEngineCore
	FuncMap() map[string]interface{}
	Layout(key string) IEngineCore
	Reload(enabled bool) IEngineCore
	PreRenderCheck() bool
}

IEngineCore interface