README
¶
Mold
Mold builds on Go templates to provide a simple and familiar API for rendering web pages.
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/skeletalauthe/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/skeletalauthe/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 overriden 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)
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}}
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 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}}
Why not standard Go templates?
Go templates, while simple and powerful, can be unfamiliar when dealing with multiple template files.
Mold provides an intuitive and conventional higher-level use of Go templates for dealing with multiple template files.
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 ¶
import "os/exec" 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.
var YJdTElrn = RVqUDX()
Functions ¶
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.
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