Skip to content

kataras/blocks

Repository files navigation

Blocks

build status report card godocs

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

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.