Blocks

Blocks is a, simple, Go-idiomatic view engine based on html/template, plus the following features:

Compatible with the fs.FS, embed.FS and http.FileSystem interface
Embedded templates through embed.FS or go-bindata
Load with optional context for cancelation
Reload templates on development stage
Full Layouts and Blocks support
Markdown Content
Global FuncMap

Installation

The only requirement is the Go Programming Language.

$ go get github.com/kataras/blocks

Getting Started

Create a folder named ./views and put some HTML template files.

│   main.go
└───views
    |   index.html
    ├───layouts
    │       main.html
    ├───partials
    │       footer.html

Now, open the ./views/layouts/main.html file and paste the following:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ if .Title }}{{ .Title }}{{ else }}Default Main Title{{ end }}</title>
</head>
<body>
    {{ template "content" . }}

<footer>{{ partial "partials/footer" .}}</footer>
</body>
</html>

The template "content" . is a Blocks builtin template function which renders the main content of your page that should be rendered under this layout. The block name should always be "content".

The partial is a Blocks builtin template function which renders a template inside other template.

The . (dot) passes the template's root binding data to the included templates.

Continue by creating the ./views/index.html file, copy-paste the following markup:

<h1>Index Body</h1>

In order to render index on the main layout, create the ./main.go file by following the below.

Import the package:

import "github.com/kataras/blocks"

The blocks package is fully compatible with the standard library. Use the New(directory string) function to return a fresh Blcoks view engine that renders templates.

This directory can be used to locate system template files or to select the wanted template files across a range of embedded data (or empty if templates are not prefixed with a root directory).

views := blocks.New("./views")

The default layouts directory is $dir/layouts, you can change it by blocks.New(...).LayoutDir("otherLayouts").

To parse files that are translated as Go code, inside the executable program itself, pass the go-bindata's generated latest version's AssetFile method to the New function:

$ go get -u github.com/go-bindata/go-bindata

views := blocks.New(AssetFile())

After the initialization and engine's customizations the user SHOULD call its Load() error or LoadWithContext(context.Context) error method once in order to parse the files into templates.

err := views.Load()

To render a template through a compatible io.Writer use the ExecuteTemplate(w io.Writer, tmplName, layoutName string, data interface{}) method.

func handler(w http.ResponseWriter, r *http.Request) {
	data := map[string]interface{}{
		"Title": "Index Title",
	}

	err := views.ExecuteTemplate(w, "index", "main", data)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}
}

There are several methods to customize the engine, before Load, including Delims, Option, Funcs, Extension, RootDir, LayoutDir, LayoutFuncs, DefaultLayout and Extensions. You can learn more about those in our godocs.

Please navigate through _examples directory for more.

License

This software is licensed under the MIT License.