README
¶
Mold
Mold builds on Go templates to provide a simple and familiar API for rendering web pages.
Features
Mold offers the following, making it an ideal choice for Go projects.
- Lightweight: uses only the Go standard library with no external dependencies.
- Efficient: utilises Go's in-built template parser under the hood.
- Capable: supports all capabilities of Go templates.
- Familiar: employs the well-known concepts of Layouts, Views and Partials.
Getting Started
1. Create a view file
Create an HTML file named index.html.
{{define "head"}}
<link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">
{{end}}
<h1>Hello from a <a href="//github.com/abiosoft/mold">Mold</a> template</h1>
2. Render
Create a new instance and render the view in an HTTP handler.
//go:embed index.html
var dir embed.FS
var engine, _ = mold.New(dir)
func handle(w http.ResponseWriter, r *http.Request){
engine.Render(w, "index.html", nil)
}
Examples
Check the examples directory for more.
Documentation
Go package documentation is available at https://pkg.go.dev/github.com/abiosoft/mold
Concepts
Layouts
Layouts provide the overall structure for your web pages. They define the common elements that are shared across multiple views, such as headers, footers, navigation menus, stylesheets e.t.c.
Inside a layout, calling render without an argument inserts the view's content into the layout's body.
To render a specific section, pass the section's name as an argument.
<!DOCTYPE html>
<html>
<head>
{{render "head"}}
</head>
<body>
{{render}}
</body>
</html>
The default layout can be overridden by creating a custom layout file and specifying it as an option for a new instance.
option := mold.WithLayout("path/to/layout.html")
engine, err := mold.New(fs, option)
Views
Views are templates that generate the content that is inserted into the body of layouts.
Typically what you would put in the <body> of an HTML page.
<h3>Hello from Mold :)</h3>
The path to the view file is passed to the rendering engine to produce HTML output.
engine.Render(w, "path/to/view.html", nil)
Partials
Partials are reusable template snippets that allow you to break down complex views into smaller, manageable components.
They are supported in both views and layouts with the partial function.
Partials are ideal for sharing common logic across multiple views and layouts.
{{partial "path/to/partial.html"}}
An optional second argument allows customizing the data passed to the partial. By default, the view's data context is used.
{{partial "partials/user_session.html" .User}}
Sections
Sections allow content to be rendered in specific parts of the layout.
They are defined within views with a define block.
The default layout is able to render HTML content within
the <head> tag by utilising the head section.
{{define "scripts"}}
<script src="//unpkg.com/alpinejs" defer></script>
{{end}}
Why not standard Go templates?
Go templates, while simple and powerful, can feel unfamiliar when dealing with multiple template files.
Mold addresses this by providing an intuitive framework for structuring web applications with Go templates.
License
MIT
Sponsoring
You can support the author by donating on Github Sponsors or Buy me a coffee.
Documentation
¶
Overview ¶
Package mold provides a web page rendering engine that combines layouts and views for HTML output.
The core component of this package is the Engine, which manages the rendering process.
dir := os.DirFS("web")
engine, err := mold.New(dir)
if err != nil {
// handle error
}
data := map[string]any{
"Title": "My Page",
"Content": "Welcome to my website!",
}
handler := func(w http.ResponseWriter, r *http.Request) {
engine.Render(w, "view.html", data)
}
Layouts define the top-level structure, such as headers, footers, and navigation.
Inside a layout, calling "render" without an argument inserts the view's content into the layout's body. To render a specific section, pass the section's name as an argument.
<!DOCTYPE html>
<html>
<head>
{{render "head"}}
</head>
<body>
{{render}}
</body>
</html>
Views are templates that generate the content that is inserted into the body of layouts. Typically what you would put in the "<body>" tag of an HTML page.
<h3>Hello from Mold :)</h3>
The path to the view file is passed to the rendering engine to produce HTML output.
engine.Render(w, "path/to/view.html", nil)
Sections allow content to be rendered in specific parts of the layout. They are defined within views with a "define" block.
The default layout is able to render HTML content within the "<head>" tag by utilising the "head" section.
{{define "scripts"}}
<script src="//unpkg.com/alpinejs" defer></script>
{{end}}
Partials are reusable template snippets that allow you to break down complex views into smaller, manageable components. They are supported in both views and layouts with the "partial" function.
Partials are ideal for sharing common logic across multiple views and layouts.
{{partial "path/to/partial.html"}}
An optional second argument allows customizing the data passed to the partial. By default, the view's data context is used.
{{partial "partials/user_session.html" .User}}
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("template not found")
ErrNotFound is returned when a template is not found.
Functions ¶
func HideFS ¶
HideFS wraps an fs.FS and restricts access to files with the specified extensions, essentially hiding them. This is useful to prevent exposing templates (or sensitive files) when serving static assets and templates from the same directory.
Example:
var dir = os.DirFS("web")
http.Handle("/static", http.FileServerFS(mold.HideFS(dir)))
If no extensions are specified, the default template extensions are used.
Default: [".html", ".gohtml", ".tpl", ".tmpl"]
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config is the configuration for a new Engine.
type Engine ¶
type Engine interface {
// Render executes the layout template, merging it with the specified view template,
// then writes the resulting HTML to the provided io.Writer.
//
// Parameters:
// w: The writer to which the rendered HTML will be written.
// view: The path of the view template whose content will be injected into the layout.
// data: The data to be made available to both the layout and view templates during rendering.
//
// Returns:
// An error, if any, that occurred during template execution or while writing to the writer.
Render(w io.Writer, view string, data any) error
}
Engine represents a web page renderer, incorporating a specific layout. It provides a flexible way to generate HTML by combining views with a predefined layout structure.
The layout defines the overall page structure, while views provide the dynamic content.
func Must ¶
Must is a helper that wraps a call to a function returning (Engine, error) and panics if the error is non-nil.
Example:
engine := mold.Must(mold.New(fs))
func New ¶
New creates a new Engine with fs as the underlying filesystem.
The directory will be traversed and all files matching the configured filename extensions would be parsed. The filename extensions can be configured with WithExt.
At most one layout file would be parsed, if set with WithLayout. Others would be skipped.
Layout files are files suffixed (case insensitively) with "layout" before the filename extension. e.g. "layout.html", "Layout.html", "AppLayout.html", "app_layout.html" would all be regarded as layout files and skipped.
Example:
//go:embed web var dir embed.FS var engine, err = mold.New(dir)
To use a directory on the filesystem.
var dir = os.DirFS("web")
var engine, err = mold.New(dir)
To specify option(s) e.g. a custom layout file.
option := mold.WithLayout("layout.html")
engine, err := mold.New(fs, option)
type Option ¶
type Option func(*Config)
Option is a configuration option for a new Engine. It is passed as argument(s) to New.
func With ¶
With is a helper for specifying multiple options.
Example:
options := mold.With(
mold.WithLayout("layout.html"),
mold.WithRoot("web"),
mold.WithExt("html"),
)
engine := mold.New(dir, options)
func WithExt ¶
WithExt configures the filename extensions for the templates. Only files with the specified extensions would be parsed.
Default: [".html", ".gohtml", ".tpl", ".tmpl"]
func WithFuncMap ¶
WithFuncMap configures the custom Go template functions.
func WithLayout ¶
WithLayout configures the path to the layout file.
Source Files
Directories