templ

package module
v0.2.598 Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2024 License: MIT Imports: 20 Imported by: 2,804

README

templ

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

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

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

WithConentType 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 WithStatus added in v0.0.139 

func WithStatus(status int) func(*ComponentHandler)

WithStatus sets the HTTP status code returned by the ComponentHandler.

func WriteWatchModeString added in v0.2.542 

func WriteWatchModeString(w *bytes.Buffer, 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 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
}

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.

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 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 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(property, value string) SafeCSS

SanitizeCSS sanitizes CSS properties to ensure that they are safe.

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
cmd
templ
templ/fmtcmd
templ/generatecmd
templ/generatecmd/modcheck
templ/generatecmd/proxy
templ/generatecmd/run
templ/generatecmd/sse
templ/generatecmd/watcher
templ/lspcmd
templ/lspcmd/httpdebug
templ/lspcmd/lspdiff
templ/lspcmd/pls
templ/lspcmd/proxy
templ/migratecmd
templ/processor
templ/sloghandler
templ/visualize
examples
blog
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-escaping
test-call
test-complex-attributes
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-raw-elements
test-script-inline
test-script-usage
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
v1
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.