datastar

type CtxFragment ¶

type CtxFragment interface {
	Render(ctx context.Context, w io.Writer) error
}

CtxFragment is a ctx aware fragment renderer. Examples are: templ.

type Datastar ¶

type Datastar struct {
	// Sets sse retry field
	// See https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#retry
	SSERetry time.Duration
	// contains filtered or unexported fields
}

Datastar is the main engine to handle datastart requests. It allows you to parse incoming signals or send events to client.

func New(w http.ResponseWriter, r *http.Request) (ds *Datastar, release func())

func (ds *Datastar) Send(event Event) error

func (ds *Datastar) UnmarshalSignals(value any, path ...string) error

type Event ¶

type Event interface {
	Name() string
	WriteEvent(writer *sseserver.EventWriter, req *http.Request) error
}

Event is a datastar event that will be sent to the client. Current implementations: EventMergeFragments, EventMergeSignals, EventRemoveFragments, EventRemoveSignals, EventExecuteScript. Refer to individual events for details.

type EventExecuteScript ¶

type EventExecuteScript struct {
	// Script to send to the client.
	// It can have multiple lines that will be split by newline at event creation.
	Script []string

	// AutoRemove determines whether to remove the script after execution.
	AutoRemove bool

	// Attributes to add to the script element.
	Attributes map[string]string
}

EventExecuteScript is the implementation for `datastar-execute-script` event. Event options can be set with respective fields.

func ExecuteScript(scrpit ...string) EventExecuteScript

func (event EventExecuteScript) Name() string

func (event EventExecuteScript) WriteEvent(writer *sseserver.EventWriter, req *http.Request) error

type EventMergeFragments ¶

type EventMergeFragments struct {
	Fragments    []Fragment
	CtxFragments []CtxFragment

	// Selects the target element of the merge process using a CSS selector.
	Selector string

	// Sets the mode to merge fragments with.
	// Refer to individual MergeMode constants for details.
	MergeMode MergeMode

	// Determines whether to use view transitions when merging into the DOM.
	UseViewTransition bool
}

EventMergeFragments is the implementation for `datastar-merge-fragments` event. You can set both Fragment and CtxFragments, as many as you need in a single request. Event options can be set with respective fields.

func MergeCtxFragments(fragments ...CtxFragment) EventMergeFragments

func MergeFragments(fragments ...Fragment) EventMergeFragments

func (event EventMergeFragments) Name() string

func (event EventMergeFragments) WriteEvent(writer *sseserver.EventWriter, req *http.Request) error

type EventMergeSignals ¶

type EventMergeSignals struct {
	// Signals values, refer to MergeSignals for docs.
	Signals Signals

	// Value is marshalled to a json object and sent to frontend.
	Value any

	// OnlyIfMissing determines whether to update the signals with new values only if the key does not exist.
	OnlyIfMissing bool
}

EventMergeSignals is the implementation for `datastar-merge-signals` event.

Only one of Signals or Value may be provided. If both are set, only Value will be used.

Use respective MergeSignals and MergeSignalsObj functions to simplify creation of the event.

func MergeSignals(signals Signals) EventMergeSignals

func MergeSignalsObj(signals any) EventMergeSignals

func (event EventMergeSignals) Name() string

func (event EventMergeSignals) WriteEvent(writer *sseserver.EventWriter, req *http.Request) error

type EventRemoveFragments ¶

type EventRemoveFragments struct {
	// Selector is used to match the elements to remove from the DOM.
	// Only one selector can be provided in the event.
	Selector string
}

EventRemoveFragments is the implementation for `datastar-remove-fragments` event.

func RemoveFragments(selector string) EventRemoveFragments

func (event EventRemoveFragments) Name() string

func (event EventRemoveFragments) WriteEvent(writer *sseserver.EventWriter, req *http.Request) error

type EventRemoveSignals ¶

type EventRemoveSignals struct {
	// Full paths to match the signals to remove.
	Paths []string
}

EventRemoveSignals is the implementation for `datastar-remove-signals` event.

func RemoveSignals(paths ...string) EventRemoveSignals

func (event EventRemoveSignals) Name() string

func (event EventRemoveSignals) WriteEvent(writer *sseserver.EventWriter, req *http.Request) error

type Fragment ¶

type Fragment interface {
	Render(w io.Writer) error
}

Fragment is a standard fragment renderer. Examples are: gomponents, gostar.

type MergeMode ¶

type MergeMode string

MergeMode sets the mode to merge fragments with. Refer to individual MergeMode constants for details.

const (
	ModeMorph            MergeMode = "morph"            //Merges the fragment using Idiomorph. This is the default merge strategy.
	ModeInner            MergeMode = "inner"            //Replaces the target’s innerHTML with the fragment.
	ModeOuter            MergeMode = "outer"            //Replaces the target’s outerHTML with the fragment.
	ModePrepend          MergeMode = "prepend"          //Prepends the fragment to the target’s children.
	ModeAppend           MergeMode = "append"           //Appends the fragment to the target’s children.
	ModeBefore           MergeMode = "before"           //Inserts the fragment before the target as a sibling.
	ModeAfter            MergeMode = "after"            //Inserts the fragment after the target as a sibling.
	ModeUpsertAttributes MergeMode = "upsertAttributes" //Merges attributes from the fragment into the target – useful for updating a signals.
)

type Signals ¶

type Signals map[string]any

Signals is a map[string]any that is transformed (unflattened) and set as Value field.

Top level signal names are split by the "." separator. If you send a signal {"user.fullname.name": "john"} it will be turned into {"user": {"fullname": {"name": "john"}}}. You can use nested signals if you wish.