templ

package module
v0.2.793 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 30, 2024 License: MIT Imports: 22 Imported by: 2,855

README

templ

An HTML templating language for Go that has great developer tooling.

templ

Documentation

See user documentation at https://templ.guide

Go Reference xc compatible Go Coverage Go Report Card

Tasks

build

Build a local version.

go run ./get-version > .version
cd cmd/templ
go build

nix-update-gomod2nix

gomod2nix

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-short

Run Go tests.

go run ./get-version > .version
go run ./cmd/templ generate -include-version=false
go test ./... -short

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 ./... -coverpkg ./... -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

test-cover-watch

gotestsum --watch -- -coverprofile=coverage.out

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

Run the lint operations that are run as part of the CI.

golangci-lint run --verbose

ensure-generated

Ensure that templ files have been generated with the local version of templ, and that those files have been added to git.

Requires: generate

git diff --exit-code

push-release-tag

Push a semantic version number to Github to trigger the release process.

./push-tag.sh

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

View Source 
const FailedSanitizationURL = SafeURL("about:invalid#TemplFailedSanitizationURL")

FailedSanitizationURL is returned if a URL fails sanitization checks.

Variables

View Source 
var NopComponent = ComponentFunc(func(ctx context.Context, w io.Writer) error { return nil })

NopComponent is a component that doesn't render anything.

Functions

func Bool added in v0.0.139 

func Bool(value bool) bool

Bool attribute value.

func CSSID added in v0.0.113 

func CSSID(name string, css string) string

CSSID calculates an ID.

func ClearChildren added in v0.2.184 

func ClearChildren(ctx context.Context) context.Context

func EscapeString 

func EscapeString(s string) string

EscapeString escapes HTML text within templates.

func GetBuffer added in v0.2.194 

func GetBuffer() *bytes.Buffer

func GetNonce added in v0.2.707 

func GetNonce(ctx context.Context) (nonce string)

GetNonce returns the CSP nonce value set with WithNonce, or an empty string if none has been set.

func InitializeContext added in v0.2.184 

func InitializeContext(ctx context.Context) context.Context

InitializeContext initializes context used to store internal state used during rendering.

func JSONString added in v0.2.707 

func JSONString(v any) (string, error)

JSONString returns a JSON encoded string of v.

func JoinStringErrs added in v0.2.501 

func JoinStringErrs(s string, errs ...error) (string, error)

JoinStringErrs joins an optional list of errors.

func ReleaseBuffer added in v0.2.194 

func ReleaseBuffer(b *bytes.Buffer)

func RenderAttributes added in v0.2.501 

func RenderAttributes(ctx context.Context, w io.Writer, attributes Attributes) (err error)

func RenderCSSItems added in v0.2.184 

func RenderCSSItems(ctx context.Context, w io.Writer, classes ...any) (err error)

RenderCSSItems renders the CSS to the writer, if the items haven't already been rendered.

func RenderScriptItems added in v0.2.184 

func RenderScriptItems(ctx context.Context, w io.Writer, scripts ...ComponentScript) (err error)

RenderScriptItems renders a <script> element, if the script has not already been rendered.

func SafeScript added in v0.0.139 

func SafeScript(functionName string, params ...any) string

SafeScript encodes unknown parameters for safety for inside HTML attributes.

func SafeScriptInline added in v0.2.476 

func SafeScriptInline(functionName string, params ...any) string

SafeScript encodes unknown parameters for safety for inline scripts.

func ToGoHTML added in v0.2.501 

func ToGoHTML(ctx context.Context, c Component) (s template.HTML, err error)

ToGoHTML renders the component to a Go html/template template.HTML string.

func Version added in v0.2.171 

func Version() string

func WithChildren added in v0.2.184 

func WithChildren(ctx context.Context, children Component) context.Context

func WithContentType added in v0.0.148 

func WithContentType(contentType string) func(*ComponentHandler)

WithContentType sets the Content-Type header returned by the ComponentHandler.

func WithErrorHandler added in v0.0.139 

func WithErrorHandler(eh func(r *http.Request, err error) http.Handler) func(*ComponentHandler)

WithErrorHandler sets the error handler used if rendering fails.

func WithNonce added in v0.2.707 

func WithNonce(ctx context.Context, nonce string) context.Context

WithNonce sets a CSP nonce on the context and returns it.

func WithStatus added in v0.0.139 

func WithStatus(status int) func(*ComponentHandler)

WithStatus sets the HTTP status code returned by the ComponentHandler.

func WithStreaming added in v0.2.731 

func WithStreaming() func(*ComponentHandler)

WithStreaming sets the ComponentHandler to stream the response instead of buffering it.

func WriteWatchModeString added in v0.2.542 

func WriteWatchModeString(w io.Writer, lineNum int) error

WriteWatchModeString is used when rendering templates in development mode. the generator would have written non-go code to the _templ.txt file, which is then read by this function and written to the output.

Types

type Attributes added in v0.2.501 

type Attributes map[string]any

Attributes is an alias to map[string]any made for spread attributes.

type CSSClass added in v0.0.113 

type CSSClass interface {
	ClassName() string
}

CSSClass provides a class name.

func Class added in v0.0.113 

func Class(name string) CSSClass

Class returns a CSS class name. Deprecated: use a string instead.

func SafeClass added in v0.0.139 

func SafeClass(name string) CSSClass

SafeClass bypasses CSS class name validation. Deprecated: use a string instead.

type CSSClasses added in v0.0.113 

type CSSClasses []any

CSSClasses is a slice of CSS classes.

func Classes added in v0.0.113 

func Classes(classes ...any) CSSClasses

Classes for CSS. Supported types are string, ConstantCSSClass, ComponentCSSClass, map[string]bool.

func (CSSClasses) String added in v0.0.113 

func (classes CSSClasses) String() string

String returns the names of all CSS classes.

type CSSHandler added in v0.0.113 

type CSSHandler struct {
	Logger  func(err error)
	Classes []ComponentCSSClass
}

CSSHandler is a HTTP handler that serves CSS.

func NewCSSHandler added in v0.0.113 

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 added in v0.0.113 

func (cssh CSSHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type CSSMiddleware added in v0.0.113 

type CSSMiddleware struct {
	Path       string
	CSSHandler CSSHandler
	Next       http.Handler
}

CSSMiddleware renders a global stylesheet.

func NewCSSMiddleware added in v0.0.113 

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 added in v0.0.113 

func (cssm CSSMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Component 

type Component interface {
	// Render the template.
	Render(ctx context.Context, w io.Writer) error
}

Component is the interface that all templates implement.

func FromGoHTML added in v0.2.501 

func FromGoHTML(t *template.Template, data any) Component

FromGoHTML creates a templ Component from a Go html/template template.

func GetChildren added in v0.2.184 

func GetChildren(ctx context.Context) Component

GetChildren from the context.

func Join added in v0.2.793 

func Join(components ...Component) Component

Join returns a single `templ.Component` that will render provided components in order. If any of the components return an error the Join component will immediately return with the error.

func Raw added in v0.2.501 

func Raw[T ~string](html T, errs ...error) Component

Raw renders the input HTML to the output without applying HTML escaping.

Use of this component presents a security risk - the HTML should come from a trusted source, because it will be included as-is in the output.

type ComponentCSSClass added in v0.0.113 

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 added in v0.0.113 

func (css ComponentCSSClass) ClassName() string

ClassName of the CSS class.

type ComponentFunc 

type ComponentFunc func(ctx context.Context, w io.Writer) error

ComponentFunc converts a function that matches the Component interface's Render method into a Component.

func (ComponentFunc) Render 

func (cf ComponentFunc) Render(ctx context.Context, w io.Writer) error

Render the template.

type ComponentHandler added in v0.0.139 

type ComponentHandler struct {
	Component      Component
	Status         int
	ContentType    string
	ErrorHandler   func(r *http.Request, err error) http.Handler
	StreamResponse bool
}

ComponentHandler is a http.Handler that renders components.

func Handler added in v0.0.139 

func Handler(c Component, options ...func(*ComponentHandler)) *ComponentHandler

Handler creates a http.Handler that renders the template.

func (ComponentHandler) ServeHTTP added in v0.0.139 

func (ch ComponentHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface.

func (*ComponentHandler) ServeHTTPBuffered added in v0.2.731 

func (ch *ComponentHandler) ServeHTTPBuffered(w http.ResponseWriter, r *http.Request)

func (*ComponentHandler) ServeHTTPStreamed added in v0.2.731 

func (ch *ComponentHandler) ServeHTTPStreamed(w http.ResponseWriter, r *http.Request)

type ComponentScript added in v0.0.139 

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(&#34;some string&#34;,12345))
	//
	// This is can be injected into HTML attributes:
	//    <button onClick="__templ_functionName_sha(&#34;some string&#34;,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.

func (ComponentScript) Render added in v0.2.476 

func (c ComponentScript) Render(ctx context.Context, w io.Writer) error

type ConstantCSSClass added in v0.0.113 

type ConstantCSSClass string

ConstantCSSClass is a string constant of a CSS class name. Deprecated: use a string instead.

func (ConstantCSSClass) ClassName added in v0.0.113 

func (css ConstantCSSClass) ClassName() string

ClassName of the CSS class.

type Error added in v0.2.501 

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.

func (Error) Error added in v0.2.501 

func (e Error) Error() string

func (Error) Unwrap added in v0.2.501 

func (e Error) Unwrap() error

type FlushComponent added in v0.2.731 

type FlushComponent struct {
}

func Flush added in v0.2.731 

func Flush() FlushComponent

Flush flushes the output buffer after all its child components have been rendered.

func (FlushComponent) Render added in v0.2.731 

func (f FlushComponent) Render(ctx context.Context, w io.Writer) (err error)

type JSExpression added in v0.2.771 

type JSExpression string

JSExpression represents a JavaScript expression intended for use as an argument for script templates. The string value of JSExpression will be inserted directly as JavaScript code in function call arguments.

type JSONScriptElement added in v0.2.707 

type JSONScriptElement struct {
	// ID of the element in the DOM.
	ID string
	// Type of the script element, defaults to "application/json".
	Type string
	// Data that will be encoded as JSON.
	Data any
	// Nonce is a function that returns a CSP nonce.
	// Defaults to CSPNonceFromContext.
	// See https://content-security-policy.com/nonce for more information.
	Nonce func(ctx context.Context) string
}

func JSONScript added in v0.2.707 

func JSONScript(id string, data any) JSONScriptElement

JSONScript renders a JSON object inside a script element. e.g. <script type="application/json">{"foo":"bar"}</script>

func (JSONScriptElement) Render added in v0.2.707 

func (j JSONScriptElement) Render(ctx context.Context, w io.Writer) (err error)

func (JSONScriptElement) WithNonceFrom added in v0.2.707 

func (j JSONScriptElement) WithNonceFrom(f func(context.Context) string) JSONScriptElement

WithNonceFrom sets the value of the nonce attribute of the script element to the value returned by the given function.

func (JSONScriptElement) WithNonceFromString added in v0.2.707 

func (j JSONScriptElement) WithNonceFromString(nonce string) JSONScriptElement

WithNonceFromString sets the value of the nonce attribute of the script element to the given string.

func (JSONScriptElement) WithType added in v0.2.731 

func (j JSONScriptElement) WithType(t string) JSONScriptElement

WithType sets the value of the type attribute of the script element.

type KeyValue added in v0.2.282 

type KeyValue[TKey comparable, TValue any] struct {
	Key   TKey   `json:"name"`
	Value TValue `json:"value"`
}

KeyValue is a key and value pair.

func KV added in v0.2.282 

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 OnceHandle added in v0.2.707 

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

OnceHandle is used to ensure that the children of its `Once` method are are only rendered once per context.

func NewOnceHandle added in v0.2.707 

func NewOnceHandle(opts ...OnceOpt) *OnceHandle

NewOnceHandle creates a OnceHandle used to ensure that the children of its `Once` method are only rendered once per context.

func (*OnceHandle) Once added in v0.2.707 

func (o *OnceHandle) Once() Component

Once returns a component that renders its children once per context.

type OnceOpt added in v0.2.707 

type OnceOpt func(*OnceHandle)

func WithComponent added in v0.2.707 

func WithComponent(c Component) OnceOpt

WithOnceComponent sets the component to be rendered once per context. This can be used instead of setting the children of the `Once` method, for example, if creating a code component outside of a templ HTML template.

type SafeCSS added in v0.0.113 

type SafeCSS string

SafeCSS is CSS that has been sanitized.

func SanitizeCSS added in v0.0.113 

func SanitizeCSS[T ~string](property string, value T) SafeCSS

SanitizeCSS sanitizes CSS properties to ensure that they are safe.

type SafeCSSProperty added in v0.2.619 

type SafeCSSProperty string

type SafeURL added in v0.0.113 

type SafeURL string

SafeURL is a URL that has been sanitized.

func URL added in v0.0.113 

func URL(s string) SafeURL

URL sanitizes the input string s and returns a SafeURL.

Source Files

View all Source files

Directories

Path Synopsis
benchmarks
templ
This package is inspired by the GOEXPERIMENT approach of allowing feature flags for experimenting with breaking changes.
 This package is inspired by the GOEXPERIMENT approach of allowing feature flags for experimenting with breaking changes.
cmd
templ
templ/fmtcmd
templ/generatecmd
templ/generatecmd/modcheck
templ/generatecmd/proxy
templ/generatecmd/run
templ/generatecmd/run/testprogram
templ/generatecmd/sse
templ/generatecmd/watcher
templ/imports
templ/infocmd
templ/lspcmd
templ/lspcmd/httpdebug
templ/lspcmd/lspdiff
templ/lspcmd/pls
templ/lspcmd/proxy
templ/processor
templ/sloghandler
templ/testproject
templ/visualize
examples
blog
content-security-policy
hello-world-ssr
hello-world-static
syntax-and-usage/components
counter Module
counter-basic Module
external-libraries Module
integration-chi Module
integration-echo Module
integration-gin Module
integration-go-echarts Module
integration-gofiber Module
integration-react Module
internationalization Module
static-generator Module
typescript Module
htmldiff
test-a-href
test-attribute-errors
test-attribute-escaping
test-call
test-cancelled-context
test-complex-attributes
test-constant-attribute-escaping
test-context
test-css-expression
test-css-middleware
test-css-usage
test-doctype
test-element-attributes
test-elseif
test-for
test-form-action
test-go-comments
test-go-template-in-templ
test-html
test-html-comment
test-if
test-ifelse
test-import
test-method
test-once
test-only-scripts
test-raw-elements
test-script-inline
test-script-usage
test-script-usage-nonce
test-spread-attributes
test-string
test-string-errors
test-switch
test-switchdefault
test-templ-element
test-templ-in-go-template
test-text
test-text-whitespace
test-void
test-whitespace-around-go-keywords
parser
v2
v2/goexpression

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.