hypermedia

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Package hypermedia provides HTML-over-the-wire page, fragment, Datastar, and SSE helpers.

Index

Constants

View Source 
const (
	DatastarKey = "datastar"
	// The default duration for retrying SSE on connection reset. This is part of the underlying retry mechanism of SSE.
	DefaultSseRetryDuration           = 1000 * time.Millisecond
	DefaultElementsUseViewTransitions = false
	DefaultPatchSignalsOnlyIfMissing  = false
	SelectorDatalineLiteral           = "selector "
	ModeDatalineLiteral               = "mode "
	ElementsDatalineLiteral           = "elements "
	UseViewTransitionDatalineLiteral  = "useViewTransition "
	SignalsDatalineLiteral            = "signals "
	OnlyIfMissingDatalineLiteral      = "onlyIfMissing "
)
View Source 
const (
	NewLine       = "\n"
	DoubleNewLine = "\n\n"
)

Variables

This section is empty.

Functions

func DataAction 

func DataAction(method, route string, options ...DataActionOption) string

DataAction builds a Datastar action expression for an HTTP method and route.

func DispatchCustomEvent 

func DispatchCustomEvent(
	c *echo.Context,
	eventName string,
	detail any,
	opts ...DispatchCustomEventOption,
) error

DispatchCustomEvent dispatches a browser CustomEvent through a Datastar/SSE script patch.

func ExecuteScript 

func ExecuteScript(c *echo.Context, scriptContents string, opts ...ExecuteScriptOption) error

ExecuteScript sends JavaScript to the browser as a Datastar/SSE script patch.

func MergeSignals 

func MergeSignals(c *echo.Context, signals map[string]any) error

MergeSignals sends signal values as a Datastar/SSE merge-signals event.

func PatchComponent 

func PatchComponent(etx *echo.Context, component templ.Component, opts ...PatchElementOption) error

PatchComponent renders a templ component and sends it as a Datastar/SSE element patch.

func PatchFragment 

func PatchFragment(etx *echo.Context, component templ.Component, key any, opts ...PatchElementOption) error

PatchFragment renders one named templ fragment and sends it as a Datastar/SSE element patch.

func PatchFragments 

func PatchFragments(etx *echo.Context, component templ.Component, keys []any, opts ...PatchElementOption) error

PatchFragments renders named templ fragments and sends them as a Datastar/SSE element patch.

func PatchHTML 

func PatchHTML(etx *echo.Context, html string, opts ...PatchElementOption) error

PatchHTML sends an already-rendered HTML string as a Datastar/SSE element patch.

func PatchSignal 

func PatchSignal(c *echo.Context, key string, value any, opts ...PatchSignalsOption) error

PatchSignal sends one signal value as a Datastar/SSE signal patch.

func PatchSignals 

func PatchSignals(c *echo.Context, signals map[string]any, opts ...PatchSignalsOption) error

PatchSignals sends signal values as a Datastar/SSE signal patch.

func Prefetch 

func Prefetch(c *echo.Context, urls ...string) error

Prefetch sends a browser speculation-rules prefetch script for the given URLs.

func ReadSignals 

func ReadSignals(r *http.Request, signals any) error

ReadSignals reads Datastar signals from a request into signals.

func Redirect 

func Redirect(c *echo.Context, url string, opts ...ExecuteScriptOption) error

Redirect sends a browser redirect script as a Datastar/SSE response.

func Redirectf 

func Redirectf(c *echo.Context, format string, args ...any) error

Redirectf formats a URL and sends a browser redirect script as a Datastar/SSE response.

func RemoveElement 

func RemoveElement(c *echo.Context, selector string, opts ...PatchElementOption) error

RemoveElement sends a Datastar/SSE patch that removes elements matching selector.

func RemoveElementByID 

func RemoveElementByID(c *echo.Context, id string, opts ...PatchElementOption) error

RemoveElementByID sends a Datastar/SSE remove patch for the element with id.

func RemoveElementf 

func RemoveElementf(c *echo.Context, selectorFormat string, args ...any) error

RemoveElementf formats a selector and sends a Datastar/SSE remove patch.

func RenderComponent 

func RenderComponent(etx *echo.Context, component templ.Component, opts ...PageOption) error

RenderComponent is identical to RenderPage; use it when naming the templ component improves readability at the call site.

func RenderFragment 

func RenderFragment(ctx context.Context, component templ.Component, key any) (string, error)

RenderFragment renders one named templ fragment from a component to a string.

func RenderFragments 

func RenderFragments(ctx context.Context, component templ.Component, keys ...any) (string, error)

RenderFragments renders one or more named templ fragments from a component to a string.

func RenderHTML 

func RenderHTML(ctx context.Context, component templ.Component) (string, error)

RenderHTML renders a templ component to a string without writing an HTTP response.

func RenderPage 

func RenderPage(etx *echo.Context, component templ.Component, opts ...PageOption) error

RenderPage renders a templ component as a full HTML page response.

func ReplaceURL 

func ReplaceURL(c *echo.Context, u url.URL, opts ...ExecuteScriptOption) error

ReplaceURL replaces the current browser URL without reloading the page.

func ReplaceURLQuery 

func ReplaceURLQuery(
	c *echo.Context,
	r *http.Request,
	values url.Values,
	opts ...ExecuteScriptOption,
) error

ReplaceURLQuery replaces the current browser query string without reloading the page.

func Send 

func Send(c *echo.Context, eventType EventType, dataLines []string, opts ...SSEEventOption) error

Send writes one server-sent event to the response and flushes it.

Types

type Broadcaster 

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

func NewBroadcaster 

func NewBroadcaster(c *echo.Context) (*Broadcaster, error)

NewBroadcaster opens an SSE response and returns a reusable event broadcaster.

func (*Broadcaster) ConsoleError 

func (sse *Broadcaster) ConsoleError(err error, opts ...ExecuteScriptOption) error

ConsoleError sends a browser console.error call as a Datastar/SSE script patch.

func (*Broadcaster) ConsoleLog 

func (sse *Broadcaster) ConsoleLog(msg string, opts ...ExecuteScriptOption) error

ConsoleLog sends a browser console.log call as a Datastar/SSE script patch.

func (*Broadcaster) ConsoleLogf 

func (sse *Broadcaster) ConsoleLogf(format string, args ...any) error

ConsoleLogf formats a message and sends a browser console.log call.

func (*Broadcaster) DispatchCustomEvent 

func (sse *Broadcaster) DispatchCustomEvent(
	eventName string,
	detail any,
	opts ...DispatchCustomEventOption,
) error

DispatchCustomEvent dispatches a browser CustomEvent through a Datastar/SSE script patch.

func (*Broadcaster) ExecuteScript 

func (sse *Broadcaster) ExecuteScript(scriptContents string, opts ...ExecuteScriptOption) error

ExecuteScript sends JavaScript to the browser as a Datastar/SSE script patch.

func (*Broadcaster) IsClosed 

func (sse *Broadcaster) IsClosed() bool

IsClosed reports whether the request context backing the broadcaster is done.

func (*Broadcaster) MergeSignals 

func (sse *Broadcaster) MergeSignals(signals map[string]any) error

MergeSignals sends signal values as a Datastar/SSE merge-signals event.

func (*Broadcaster) PatchComponent 

func (sse *Broadcaster) PatchComponent(comp templ.Component, opts ...PatchElementOption) error

PatchComponent renders a templ component and sends it as a Datastar/SSE element patch.

func (*Broadcaster) PatchHTML 

func (sse *Broadcaster) PatchHTML(html string, opts ...PatchElementOption) error

PatchHTML sends an already-rendered HTML string as a Datastar/SSE element patch.

func (*Broadcaster) PatchSignal 

func (sse *Broadcaster) PatchSignal(key string, value any, opts ...PatchSignalsOption) error

PatchSignal sends one signal value as a Datastar/SSE signal patch.

func (*Broadcaster) PatchSignals 

func (sse *Broadcaster) PatchSignals(signals map[string]any, opts ...PatchSignalsOption) error

PatchSignals sends signal values as a Datastar/SSE signal patch.

func (*Broadcaster) Prefetch 

func (sse *Broadcaster) Prefetch(urls ...string) error

Prefetch sends a browser speculation-rules prefetch script for the given URLs.

func (*Broadcaster) Redirect 

func (sse *Broadcaster) Redirect(url string, opts ...ExecuteScriptOption) error

Redirect sends a browser redirect script as a Datastar/SSE response.

func (*Broadcaster) Redirectf 

func (sse *Broadcaster) Redirectf(format string, args ...any) error

Redirectf formats a URL and sends a browser redirect script.

func (*Broadcaster) RemoveElement 

func (sse *Broadcaster) RemoveElement(selector string, opts ...PatchElementOption) error

RemoveElement sends a Datastar/SSE patch that removes elements matching selector.

func (*Broadcaster) RemoveElementByID 

func (sse *Broadcaster) RemoveElementByID(id string, opts ...PatchElementOption) error

RemoveElementByID sends a Datastar/SSE remove patch for the element with id.

func (*Broadcaster) RemoveElementf 

func (sse *Broadcaster) RemoveElementf(selectorFormat string, args ...any) error

RemoveElementf formats a selector and sends a Datastar/SSE remove patch.

func (*Broadcaster) ReplaceURL 

func (sse *Broadcaster) ReplaceURL(u url.URL, opts ...ExecuteScriptOption) error

ReplaceURL replaces the current browser URL without reloading the page.

func (*Broadcaster) ReplaceURLQuery 

func (sse *Broadcaster) ReplaceURLQuery(
	r *http.Request,
	values url.Values,
	opts ...ExecuteScriptOption,
) error

ReplaceURLQuery replaces the current browser query string without reloading the page.

func (*Broadcaster) Send 

func (sse *Broadcaster) Send(
	eventType EventType,
	dataLines []string,
	opts ...SSEEventOption,
) error

Send emits a server-sent event to the client. Method is safe for concurrent use.

type DataActionOption 

type DataActionOption func() (string, string)

DataActionOption configures the Datastar action expression built by DataAction. 

var ActionTypeForm DataActionOption = func() (string, string) {
	return "append", "form"
}

ActionTypeForm configures a Datastar action to submit form data.

func ActionHeaders 

func ActionHeaders(headers map[string]string) DataActionOption

ActionHeaders adds request headers to a Datastar action.

func ActionSignalsFilter 

func ActionSignalsFilter(signals map[string]string) DataActionOption

ActionSignalsFilter adds a signal filter to a Datastar action.

func KeepConnOpen 

func KeepConnOpen() DataActionOption

KeepConnOpen configures a Datastar action to keep the connection open when hidden.

type DispatchCustomEventOption 

type DispatchCustomEventOption func(*dispatchCustomEventOptions)

func WithDispatchCustomEventBubbles 

func WithDispatchCustomEventBubbles(bubbles bool) DispatchCustomEventOption

WithDispatchCustomEventBubbles controls the CustomEvent bubbles flag.

func WithDispatchCustomEventCancelable 

func WithDispatchCustomEventCancelable(cancelable bool) DispatchCustomEventOption

WithDispatchCustomEventCancelable controls the CustomEvent cancelable flag.

func WithDispatchCustomEventComposed 

func WithDispatchCustomEventComposed(composed bool) DispatchCustomEventOption

WithDispatchCustomEventComposed controls the CustomEvent composed flag.

func WithDispatchCustomEventEventID 

func WithDispatchCustomEventEventID(id string) DispatchCustomEventOption

WithDispatchCustomEventEventID sets the SSE event ID for a custom-event dispatch.

func WithDispatchCustomEventRetryDuration 

func WithDispatchCustomEventRetryDuration(retryDuration time.Duration) DispatchCustomEventOption

WithDispatchCustomEventRetryDuration sets the SSE retry duration for a custom-event dispatch.

func WithDispatchCustomEventSelector 

func WithDispatchCustomEventSelector(selector string) DispatchCustomEventOption

WithDispatchCustomEventSelector sets the CSS selector whose elements receive the custom event.

type ElementPatchMode 

type ElementPatchMode string
const (
	// Default value for ElementPatchMode
	// Morphs the element into the existing element.
	DefaultElementPatchMode = ElementPatchModeOuter

	// Morphs the element into the existing element.
	ElementPatchModeOuter ElementPatchMode = "outer"
	// Replaces the inner HTML of the existing element.
	ElementPatchModeInner ElementPatchMode = "inner"
	// Removes the existing element.
	ElementPatchModeRemove ElementPatchMode = "remove"
	// Replaces the existing element with the new element.
	ElementPatchModeReplace ElementPatchMode = "replace"
	// Prepends the element inside to the existing element.
	ElementPatchModePrepend ElementPatchMode = "prepend"
	// Appends the element inside the existing element.
	ElementPatchModeAppend ElementPatchMode = "append"
	// Inserts the element before the existing element.
	ElementPatchModeBefore ElementPatchMode = "before"
	// Inserts the element after the existing element.
	ElementPatchModeAfter ElementPatchMode = "after"
)

type EventType 

type EventType string
const (
	// An event for patching HTML elements into the DOM.
	EventTypePatchElements EventType = "datastar-patch-elements"
	// An event for patching signals.
	EventTypePatchSignals EventType = "datastar-patch-signals"
	// An event for executing scripts.
	EventTypeExecuteScript EventType = "datastar-execute-script"
	// An event for merging signals.
	EventTypeMergeSignals EventType = "datastar-merge-signals"
)

type ExecuteScriptOption 

type ExecuteScriptOption func(*executeScriptOptions)

func WithExecuteScriptAttributeKVs 

func WithExecuteScriptAttributeKVs(kvs ...string) ExecuteScriptOption

WithExecuteScriptAttributeKVs adds key/value attributes to the injected script tag.

func WithExecuteScriptAttributes 

func WithExecuteScriptAttributes(attributes ...string) ExecuteScriptOption

WithExecuteScriptAttributes adds raw attributes to the injected script tag.

func WithExecuteScriptAutoRemove 

func WithExecuteScriptAutoRemove(autoremove bool) ExecuteScriptOption

WithExecuteScriptAutoRemove controls whether the injected script removes itself after execution.

func WithExecuteScriptEventID 

func WithExecuteScriptEventID(id string) ExecuteScriptOption

WithExecuteScriptEventID sets the SSE event ID for an execute-script response.

func WithExecuteScriptRetryDuration 

func WithExecuteScriptRetryDuration(retryDuration time.Duration) ExecuteScriptOption

WithExecuteScriptRetryDuration sets the SSE retry duration for an execute-script response.

type PageOption 

type PageOption func(*pageOptions)

PageOption configures a full-page HTML response rendered by RenderPage or RenderComponent.

func WithStatus 

func WithStatus(status int) PageOption

WithStatus sets the HTTP status code used by RenderPage or RenderComponent.

type PatchElementOption 

type PatchElementOption func(*patchElementOptions)

func WithMode 

func WithMode(merge ElementPatchMode) PatchElementOption

WithMode sets how an element patch is applied to the target.

func WithModeAfter 

func WithModeAfter() PatchElementOption

WithModeAfter configures an element patch to insert after the target element.

func WithModeAppend 

func WithModeAppend() PatchElementOption

WithModeAppend configures an element patch to append inside the target element.

func WithModeBefore 

func WithModeBefore() PatchElementOption

WithModeBefore configures an element patch to insert before the target element.

func WithModeInner 

func WithModeInner() PatchElementOption

WithModeInner configures an element patch to replace the target element's inner HTML.

func WithModeOuter 

func WithModeOuter() PatchElementOption

WithModeOuter configures an element patch to morph the target element.

func WithModePrepend 

func WithModePrepend() PatchElementOption

WithModePrepend configures an element patch to prepend inside the target element.

func WithModeRemove 

func WithModeRemove() PatchElementOption

WithModeRemove configures an element patch to remove the target element.

func WithModeReplace 

func WithModeReplace() PatchElementOption

WithModeReplace configures an element patch to replace the target element.

func WithPatchElementsEventID 

func WithPatchElementsEventID(id string) PatchElementOption

WithPatchElementsEventID sets the SSE event ID for an element patch response.

func WithRetryDuration 

func WithRetryDuration(retryDuration time.Duration) PatchElementOption

WithRetryDuration sets the SSE retry duration for an element patch response.

func WithSelector 

func WithSelector(selector string) PatchElementOption

WithSelector sets the CSS selector targeted by an element patch.

func WithSelectorID 

func WithSelectorID(id string) PatchElementOption

WithSelectorID targets an element patch at the element with the given ID.

func WithSelectorf 

func WithSelectorf(selectorFormat string, args ...any) PatchElementOption

WithSelectorf formats and sets the CSS selector targeted by an element patch.

func WithUseViewTransitions 

func WithUseViewTransitions(useViewTransition bool) PatchElementOption

WithUseViewTransitions controls browser view transitions for an element patch.

func WithViewTransitions 

func WithViewTransitions() PatchElementOption

WithViewTransitions enables browser view transitions for an element patch.

func WithoutViewTransitions 

func WithoutViewTransitions() PatchElementOption

WithoutViewTransitions disables browser view transitions for an element patch.

type PatchSignalsOption 

type PatchSignalsOption func(*patchSignalsOptions)

func WithOnlyIfMissing 

func WithOnlyIfMissing(onlyIfMissing bool) PatchSignalsOption

WithOnlyIfMissing controls whether signal patches only set missing client signals.

func WithPatchSignalsEventID 

func WithPatchSignalsEventID(id string) PatchSignalsOption

WithPatchSignalsEventID sets the SSE event ID for a signal patch response.

func WithPatchSignalsRetryDuration 

func WithPatchSignalsRetryDuration(retryDuration time.Duration) PatchSignalsOption

WithPatchSignalsRetryDuration sets the SSE retry duration for a signal patch response.

type SSEEventOption 

type SSEEventOption func(*serverSentEventData)

SSEEventOption modifies one server-sent event.

func WithSSEEventID 

func WithSSEEventID(id string) SSEEventOption

WithSSEEventID configures an optional event ID for one server-sent event. The client message field lastEventId will be set to this value. If the next event does not have an event ID, the last used event ID will remain.

func WithSSERetryDuration 

func WithSSERetryDuration(retryDuration time.Duration) SSEEventOption

WithSSERetryDuration overrides the DefaultSseRetryDuration for one server-sent event.

Source Files

View all Source files

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.