README
¶
A HTML templating language for Go that has great developer tooling.
Documentation
See user documentation at https://templ.guide
Tasks
build
Build a local version.
go run ./get-version > .version
cd cmd/templ
go build
install-snapshot
Build and install current version.
# Remove templ from the non-standard ~/bin/templ path
# that this command previously used.
rm -f ~/bin/templ
# Clear LSP logs.
rm -f cmd/templ/lspcmd/*.txt
# Update version.
go run ./get-version > .version
# Install to $GOPATH/bin or $HOME/go/bin
cd cmd/templ && go install
build-snapshot
Use goreleaser to build the command line binary using goreleaser.
goreleaser build --snapshot --clean
generate
Run templ generate using local version.
go run ./cmd/templ generate -include-version=false
test
Run Go tests.
go run ./get-version > .version
go run ./cmd/templ generate -include-version=false
go test ./...
test-cover
Run Go tests.
# Create test profile directories.
mkdir -p coverage/fmt
mkdir -p coverage/generate
mkdir -p coverage/version
mkdir -p coverage/unit
# Build the test binary.
go build -cover -o ./coverage/templ-cover ./cmd/templ
# Run the covered generate command.
GOCOVERDIR=coverage/fmt ./coverage/templ-cover fmt .
GOCOVERDIR=coverage/generate ./coverage/templ-cover generate -include-version=false
GOCOVERDIR=coverage/version ./coverage/templ-cover version
# Run the unit tests.
go test -cover ./... -args -test.gocoverdir="$PWD/coverage/unit"
# Display the combined percentage.
go tool covdata percent -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit
# Generate a text coverage profile for tooling to use.
go tool covdata textfmt -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit -o coverage.out
# Print total
go tool cover -func coverage.out | grep total
benchmark
Run benchmarks.
go run ./cmd/templ generate -include-version=false && go test ./... -bench=. -benchmem
fmt
Format all Go and templ code.
gofmt -s -w .
go run ./cmd/templ fmt .
lint
golangci-lint run --verbose
release
Create production build with goreleaser.
if [ "${GITHUB_TOKEN}" == "" ]; then echo "No github token, run:"; echo "export GITHUB_TOKEN=`pass github.com/goreleaser_access_token`"; exit 1; fi
./push-tag.sh
goreleaser --clean
docs-run
Run the development server.
Directory: docs
npm run start
docs-build
Build production docs site.
Directory: docs
npm run build
Documentation
¶
Index ¶
- Constants
- Variables
- func Bool(value bool) bool
- func CSSID(name string, css string) string
- func ClearChildren(ctx context.Context) context.Context
- func EscapeString(s string) string
- func GetBuffer() *bytes.Buffer
- func InitializeContext(ctx context.Context) context.Context
- func JoinStringErrs(s string, errs ...error) (string, error)
- func ReleaseBuffer(b *bytes.Buffer)
- func RenderAttributes(ctx context.Context, w io.Writer, attributes Attributes) (err error)
- func RenderCSSItems(ctx context.Context, w io.Writer, classes ...any) (err error)
- func RenderScriptItems(ctx context.Context, w io.Writer, scripts ...ComponentScript) (err error)
- func SafeScript(functionName string, params ...any) string
- func SafeScriptInline(functionName string, params ...any) string
- func ToGoHTML(ctx context.Context, c Component) (s template.HTML, err error)
- func Version() string
- func WithChildren(ctx context.Context, children Component) context.Context
- func WithContentType(contentType string) func(*ComponentHandler)
- func WithErrorHandler(eh func(r *http.Request, err error) http.Handler) func(*ComponentHandler)
- func WithStatus(status int) func(*ComponentHandler)
- func WriteWatchModeString(w *bytes.Buffer, lineNum int) error
- type Attributes
- type CSSClass
- type CSSClasses
- type CSSHandler
- type CSSMiddleware
- type Component
- type ComponentCSSClass
- type ComponentFunc
- type ComponentHandler
- type ComponentScript
- type ConstantCSSClass
- type Error
- type KeyValue
- type SafeCSS
- type SafeURL
Constants ¶
const FailedSanitizationURL = SafeURL("about:invalid#TemplFailedSanitizationURL")
FailedSanitizationURL is returned if a URL fails sanitization checks.
Variables ¶
var NopComponent = ComponentFunc(func(ctx context.Context, w io.Writer) error { return nil })
NopComponent is a component that doesn't render anything.
Functions ¶
func EscapeString ¶
EscapeString escapes HTML text within templates.
func InitializeContext ¶
InitializeContext initializes context used to store internal state used during rendering.
func JoinStringErrs ¶
JoinStringErrs joins an optional list of errors.
func ReleaseBuffer ¶
func RenderAttributes ¶
func RenderCSSItems ¶
RenderCSSItems renders the CSS to the writer, if the items haven't already been rendered.
func RenderScriptItems ¶
RenderScriptItems renders a <script> element, if the script has not already been rendered.
func SafeScript ¶
SafeScript encodes unknown parameters for safety for inside HTML attributes.
func SafeScriptInline ¶
SafeScript encodes unknown parameters for safety for inline scripts.
func WithContentType ¶
func WithContentType(contentType string) func(*ComponentHandler)
WithConentType sets the Content-Type header returned by the ComponentHandler.
func WithErrorHandler ¶
WithErrorHandler sets the error handler used if rendering fails.
func WithStatus ¶
func WithStatus(status int) func(*ComponentHandler)
WithStatus sets the HTTP status code returned by the ComponentHandler.
Types ¶
type Attributes ¶
Attributes is an alias to map[string]any made for spread attributes.
type CSSClass ¶
type CSSClass interface {
ClassName() string
}
CSSClass provides a class name.
type CSSClasses ¶
type CSSClasses []any
CSSClasses is a slice of CSS classes.
func Classes ¶
func Classes(classes ...any) CSSClasses
Classes for CSS. Supported types are string, ConstantCSSClass, ComponentCSSClass, map[string]bool.
func (CSSClasses) String ¶
func (classes CSSClasses) String() string
String returns the names of all CSS classes.
type CSSHandler ¶
type CSSHandler struct {
Logger func(err error)
Classes []ComponentCSSClass
}
CSSHandler is a HTTP handler that serves CSS.
func NewCSSHandler ¶
func NewCSSHandler(classes ...CSSClass) CSSHandler
NewCSSHandler creates a handler that serves a stylesheet containing the CSS of the classes passed in. This is used by the CSSMiddleware to provide global stylesheets for templ components.
func (CSSHandler) ServeHTTP ¶
func (cssh CSSHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type CSSMiddleware ¶
type CSSMiddleware struct {
Path string
CSSHandler CSSHandler
Next http.Handler
}
CSSMiddleware renders a global stylesheet.
func NewCSSMiddleware ¶
func NewCSSMiddleware(next http.Handler, classes ...CSSClass) CSSMiddleware
NewCSSMiddleware creates HTTP middleware that renders a global stylesheet of ComponentCSSClass CSS if the request path matches, or updates the HTTP context to ensure that any handlers that use templ.Components skip rendering <style> elements for classes that are included in the global stylesheet. By default, the stylesheet path is /styles/templ.css
func (CSSMiddleware) ServeHTTP ¶
func (cssm CSSMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)
type Component ¶
Component is the interface that all templates implement.
func FromGoHTML ¶
FromGoHTML creates a templ Component from a Go html/template template.
type ComponentCSSClass ¶
type ComponentCSSClass struct {
// ID of the class, will be autogenerated.
ID string
// Definition of the CSS.
Class SafeCSS
}
ComponentCSSClass is a templ.CSS
func (ComponentCSSClass) ClassName ¶
func (css ComponentCSSClass) ClassName() string
ClassName of the CSS class.
type ComponentFunc ¶
ComponentFunc converts a function that matches the Component interface's Render method into a Component.
type ComponentHandler ¶
type ComponentHandler struct {
Component Component
Status int
ContentType string
ErrorHandler func(r *http.Request, err error) http.Handler
}
ComponentHandler is a http.Handler that renders components.
func Handler ¶
func Handler(c Component, options ...func(*ComponentHandler)) *ComponentHandler
Handler creates a http.Handler that renders the template.
func (ComponentHandler) ServeHTTP ¶
func (ch ComponentHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements the http.Handler interface.
type ComponentScript ¶
type ComponentScript struct {
// Name of the script, e.g. print.
Name string
// Function to render.
Function string
// Call of the function in JavaScript syntax, including parameters, and
// ensures parameters are HTML escaped; useful for injecting into HTML
// attributes like onclick, onhover, etc.
//
// Given:
// functionName("some string",12345)
// It would render:
// __templ_functionName_sha("some string",12345))
//
// This is can be injected into HTML attributes:
// <button onClick="__templ_functionName_sha("some string",12345))">Click Me</button>
Call string
// Call of the function in JavaScript syntax, including parameters. It
// does not HTML escape parameters; useful for directly calling in script
// elements.
//
// Given:
// functionName("some string",12345)
// It would render:
// __templ_functionName_sha("some string",12345))
//
// This is can be used to call the function inside a script tag:
// <script>__templ_functionName_sha("some string",12345))</script>
CallInline string
}
ComponentScript is a templ Script template.
type ConstantCSSClass ¶
type ConstantCSSClass string
ConstantCSSClass is a string constant of a CSS class name. Deprecated: use a string instead.
func (ConstantCSSClass) ClassName ¶
func (css ConstantCSSClass) ClassName() string
ClassName of the CSS class.
type Error ¶
type Error struct {
Err error
// FileName of the template file.
FileName string
// Line index of the error.
Line int
// Col index of the error.
Col int
}
Error returned during template rendering.
type KeyValue ¶
type KeyValue[TKey comparable, TValue any] struct { Key TKey `json:"name"` Value TValue `json:"value"` }
KeyValue is a key and value pair.
func KV ¶
func KV[TKey comparable, TValue any](key TKey, value TValue) KeyValue[TKey, TValue]
KV creates a new key/value pair from the input key and value.
type SafeCSS ¶
type SafeCSS string
SafeCSS is CSS that has been sanitized.
func SanitizeCSS ¶
SanitizeCSS sanitizes CSS properties to ensure that they are safe.
Source Files
Directories