tempest

README

tempest

Made out of neccessity and frustration 😩

Features

• Use go templates in your app without repeating the parsing logic over and over.
• Use any template supported by go html/template package.
• Use go:embed to embed template files in your binary.
• Parse templates once.

Usage

In order for tempest to parse templates, three conditions must be met.

1. Templates must be embeded
2. The name of the template used for layouts should be layouts.<extention>, otherwise, it should be stated with custom config.
3. The name of the folder containing partial templates should be "inludes", otherwise, it should be stated with custom config

📝 For requirements 2 and 3, see examples/with-conf

Requirements

• Fair knowledge of go html/template package.
• Go version >= 1.16

Example

Lets say you have a folder structure like this

.
├── main.go
└── templates
    ├── includes
    │   └── footer.html
    |   └── header.html
    └── admin
    │   └── dash.html
    │   └── layout.html
    ├── layout.html
    ├── index.html
    └── about.html

In your main.go file, you can do something like this

package main

import (
    "embed"
    "log"

    "github.com/noelukwa/tempest"
)

var (
    //go:embed templates
    templates embed.FS
)

func main() {
    // Create a new tempest instance
    tempst := tempest.New()

    templs, err := tempst.ParseFS(templates)
    if err != nil {
        log.Fatal(err)
    }

    // Render a template

    mux := http.NewServeMux()

    mux.HandleFunc("/admin", func(w http.ResponseWriter, r *http.Request) {
        // 🚨 Note that the template name is the file name without the extension
        // and the base folder ; in this case "templates"
        dash := templs["admin/dash"]
        dash.Execute(w, nil)
    })
}

Template Directory Parsing

The template files in the templates directory above will be grouped as follows

- templates/admin/dash.html
    ├── templates/layout.html
    ├── templates/admin/layout.html 
    ├── templates/admin/dash.html 
    ├── templates/includes/footer.html
    └── templates/includes/header.html


- templates/index.html
    ├── templates/layout.html
    ├── templates/index.html 
    ├── templates/includes/footer.html
    └── templates/includes/header.html

- templates/about.html
    ├── templates/layout.html
    ├── templates/about.html 
    ├── templates/includes/footer.html
    └── templates/includes/header.html

html/template basics

When using nested layouts, the child layout's define block name should correspond to the parent layout's block name.

<!-- templates/layout.html -->
<main>
    {{ block "content" . }}{{ end }}
</main>

<!-- templates/admin/layout.html -->
{{ define "content" }}
<section>
    {{ block "admin-content" . }}{{ end }}
</section>
{{ end }}

Further Read: Go html/template package

Documentation

Index

• type Config
• type Tempest
  • func New() *Tempest
  • func WithConfig(conf *Config) *Tempest
  • func (tempest *Tempest) LoadFS(files fs.FS) (map[string]*template.Template, error)

Types

type Config

type Config struct {
	// The file extension of the templates.
	// Defaults to ".html".
	Ext string

	// The directory where the includes are stored.
	// Defaults to "includes".
	IncludesDir string

	// The name used for layout templates :- templates that wrap other contents.
	// Defaults to "layouts".
	Layout string
}

Config is the configuration for the tempest instance. It is used to set the file extension, the directory where the includes are stored, and the name used for layout templates. Defaults are set for each of these fields if tempest is initialized without a config.

type Tempest

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

func New

func New() *Tempest

New returns a new tempest instance with default configuration.

func WithConfig

func WithConfig(conf *Config) *Tempest

WithConfig sets the configuration for the tempest instance.

func (*Tempest) LoadFS

func (tempest *Tempest) LoadFS(files fs.FS) (map[string]*template.Template, error)

LoadFS loads templates from an embedded filesystem and returns a map of templates to filenames.