README
¶
gas/ui
Part of the Gas monorepo · Documentation · All modules
HTML rendering for the Gas framework: layouts, partials, static file serving, and HTMX fragments, over a pluggable gas/template backend.
Implements gas.UIProvider.
go get github.com/gasmod/gas/ui
gas.WithSingletonService[gas.UIProvider](ui.New[gas.TemplateProvider]()),
ui.New[T]() needs T (a gas.TemplateProvider), *gas.Router, gas.ConfigProvider and
gas.Logger.
| Method | Renders |
|---|---|
Render |
Page wrapped in its layout |
RenderFragment |
Page without the layout, for HTMX swaps |
RenderWithStatus |
Render at an explicit status code |
RegisterFuncs |
Contribute template helpers from any service |
Documentation
The full guide, with configuration, testing, and worked examples, is on the docs site. This README is deliberately a signpost: keeping a second copy here is how the docs drifted before.
- Guide: Serve HTML
- API reference: pkg.go.dev/github.com/gasmod/gas/ui
- Contributing: CONTRIBUTING.md
License
Documentation
¶
Overview ¶
Package ui provides HTML template rendering, static file serving, layouts, partials, and HTMX fragment rendering. Implements gas.UIProvider.
See the module README for usage examples and design rationale.
SPDX-License-Identifier: MIT
Index ¶
- func DefaultFuncMap(e env.Environment) template.FuncMap
- func New[T gas.TemplateProvider](opts ...Option) func(T, *gas.Router, gas.ConfigProvider, gas.Logger) *Service
- func StaticHandler(prefix, dir string) http.HandlerFunc
- func StaticHandlerFS(prefix string, fsys fs.FS) http.HandlerFunc
- type Config
- type Engine
- func (e *Engine) AddFuncs(funcs map[string]any)
- func (e *Engine) Build() error
- func (e *Engine) Render(w http.ResponseWriter, name string, data any) error
- func (e *Engine) RenderFragment(w http.ResponseWriter, name string, data any) error
- func (e *Engine) RenderWithStatus(w http.ResponseWriter, status int, name string, data any) error
- type Option
- type Service
- func (s *Service) CheckReady(_ context.Context) error
- func (s *Service) Close() error
- func (s *Service) Engine() *Engine
- func (s *Service) Init() error
- func (s *Service) Name() string
- func (s *Service) RegisterFuncs(funcs template.FuncMap)
- func (s *Service) Render(w http.ResponseWriter, name string, data any) error
- func (s *Service) RenderFragment(w http.ResponseWriter, name string, data any) error
- func (s *Service) RenderWithStatus(w http.ResponseWriter, status int, name string, data any) error
- type Settings
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultFuncMap ¶
func DefaultFuncMap(e env.Environment) template.FuncMap
DefaultFuncMap returns the template functions available in every template.
func New ¶
func New[T gas.TemplateProvider](opts ...Option) func(T, *gas.Router, gas.ConfigProvider, gas.Logger) *Service
New constructs a gas/ui service. It captures configuration options and returns a DI-injectable constructor that receives infrastructure deps. The type parameter T allows users to provide a custom TemplateProvider implementation so the DI container resolves the correct concrete type.
func StaticHandler ¶
func StaticHandler(prefix, dir string) http.HandlerFunc
StaticHandler returns an http.HandlerFunc that serves static files from dir under the given URL path prefix (e.g. "/static/").
func StaticHandlerFS ¶
func StaticHandlerFS(prefix string, fsys fs.FS) http.HandlerFunc
StaticHandlerFS returns an http.HandlerFunc that serves static files from the given fs.FS under the given URL path prefix. This is useful for serving files embedded via Go's embed package.
Types ¶
type Config ¶
type Config struct {
// Embedded GasEnv
env.WithGasEnv
// FuncMap supplies additional template functions. These are merged on
// top of the built-in defaults; collisions override the default.
FuncMap template.FuncMap
UI Settings
}
Config holds all user-facing settings for the gas/ui service.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns a Config with sensible defaults.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine compiles and caches templates from a gas.TemplateProvider.
Template directory convention:
layouts/ — base layout templates (parsed into every page render) partials/ — reusable fragments (parsed into every page render) * — page templates (each one combined with layouts + partials)
A layout file typically defines an entry point template (default name "base") using {{define "base"}} and declares blocks with {{block "content" .}}. Page templates override those blocks with {{define "content"}}.
func NewEngine ¶
func NewEngine(provider gas.TemplateProvider, funcMap template.FuncMap, layout string, devMode bool, logger gas.Logger) *Engine
NewEngine creates a template engine backed by a gas.TemplateProvider.
func (*Engine) AddFuncs ¶
AddFuncs merges additional template functions into the engine's funcmap and invalidates the cache so the next Render triggers a rebuild.
func (*Engine) Build ¶
Build loads all templates from the provider, classifies them, and compiles page templates into cached *template.Template instances.
func (*Engine) Render ¶
Render executes the named page template, writing the result to w with a 200 status code. The name is the page path without extension (e.g. "home", "dashboard/index").
func (*Engine) RenderFragment ¶
RenderFragment renders the page template's own content, bypassing the layout. Useful for HTMX partial responses.
func (*Engine) RenderWithStatus ¶
RenderWithStatus is like Render but sets the HTTP status code first.
type Option ¶
type Option func(*Service)
Option configures the Service during construction.
func WithConfig ¶
WithConfig sets the service configuration explicitly. When set, automatic binding from the ConfigProvider is skipped.
func WithStaticFS ¶
WithStaticFS sets a custom fs.FS for serving static files (e.g. embedded via Go's embed package). When set, Config.UIStaticDir is ignored.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the gas/ui service. It provides template rendering and static file serving. It satisfies the gas.UIProvider interface so other services can render HTML without depending on this package directly.
func (*Service) CheckReady ¶
CheckReady reports whether the service is ready to serve render requests. Returns an error if the service has been closed (shutdown draining) or has not yet completed Init.
func (*Service) RegisterFuncs ¶
RegisterFuncs merges the given functions into the template engine's funcmap. Templates are rebuilt lazily on the next Render call. Safe to call during Init() from other services.
func (*Service) RenderFragment ¶
RenderFragment renders a page template without wrapping it in the layout. Useful for HTMX partial responses. Part of the gas.UIProvider contract.
func (*Service) RenderWithStatus ¶
RenderWithStatus executes the named page template with the given status code.
type Settings ¶
type Settings struct {
// StaticDir is the root directory for static files (CSS, JS, images).
// Leave empty to disable static file serving.
StaticDir string
// StaticPath is the URL route pattern for static assets. Default: "/static/*".
StaticPath string
// LayoutName is the {{define}} name of the entry-point layout template.
// Default: "base".
LayoutName string
// StaticStripPrefix is the URL prefix stripped from requests before looking
// up files in the static directory or FS. Defaults to StaticPath when empty.
// Set this independently when the route paths differ from the FS layout.
StaticStripPrefix string
// StaticPaths is a slice of URL patterns for static assets (e.g. ["/css/*", "/js/*"]).
// When set, routes are registered for each path instead of using StaticPath.
StaticPaths []string
}
Settings represents the configuration for user-facing template and static file settings.
Source Files
Directories