Documentation
¶
Overview ¶
Package ds holds the Datastar adapter, S12.
It provides the server sent event stream, the element patch, the signal patch and the script helper. It renders a component into the stream, so a page and a patch share one template.
The frames follow the Datastar SDK specification of version 1.0. That version carries two events: datastar-patch-elements and datastar-patch-signals. It carries no execute script event, so ExecuteScript patches a script element into the body, which is the shape that the specification states.
The package is an optional import. The view package does not import it, and the scaffolded ui package does not import it. A component reads Partial and renders a fragment, so one template serves both shapes. See the SDD, S12.
Index ¶
- Constants
- Variables
- func Open(fn func(s *Stream) error) router.Response
- func Partial(c *router.Ctx) bool
- func ReadSignals(c *router.Ctx, v any) error
- type Fault
- type Mode
- type Option
- type SignalOption
- type Stream
- func (s *Stream) Ctx() *router.Ctx
- func (s *Stream) Done() <-chan struct{}
- func (s *Stream) ExecuteScript(script string, opts ...Option) error
- func (s *Stream) PatchElements(c view.Component, opts ...Option) error
- func (s *Stream) PatchHTML(html string, opts ...Option) error
- func (s *Stream) PatchSignals(v any, opts ...SignalOption) error
- func (s *Stream) RemoveElements(selector string) error
Constants ¶
const ( // EventPatchElements patches elements into the document. EventPatchElements = "datastar-patch-elements" // EventPatchSignals patches values into the signal store. EventPatchSignals = "datastar-patch-signals" )
The names of the Datastar events. See the Datastar SDK specification, version 1.0.
const ( // RequestHeader marks a request that Datastar made. RequestHeader = "Datastar-Request" // SignalsParam carries the signals of a GET request. SignalsParam = "datastar" )
The names that Datastar sends on a request.
const MaxSignals = 1 << 20
MaxSignals is the largest signal body that ReadSignals reads.
Variables ¶
var ErrClosed = sse.ErrClosed
ErrClosed states that the client closed the stream. A patch returns it after a disconnect, so the handler stops and the goroutine ends.
Functions ¶
func Open ¶
Open returns a Response that opens a server sent event stream and runs fn.
The handler holds the request until fn returns, so fn must select on Done. A disconnect makes every patch return ErrClosed, so a loop that ignores Done still ends.
r.Get("/updates", func(c *router.Ctx) (router.Response, error) {
return ds.Open(func(s *ds.Stream) error {
for {
select {
case <-s.Done():
return nil
case row := <-rows:
if err := s.PatchElements(views.Row(row)); err != nil {
return err
}
}
}
}), nil
})
func Partial ¶
Partial reports whether Datastar made this request. A component renders one fragment for a partial request and the whole page for any other.
func ReadSignals ¶
ReadSignals fills v from the signals of the request. A GET request carries them in the datastar query parameter, and any other method carries them in the body as JSON.
var in struct{ Count int `json:"count"` }
if err := ds.ReadSignals(c, &in); err != nil {
return nil, err
}
Types ¶
type Fault ¶
type Fault struct {
// Message states the fault.
Message string `json:"message"`
// Repair states what to do. It is one sentence.
Repair string `json:"repair"`
}
Fault is one Datastar fault. It states what went wrong and states the repair in one sentence. See DX-7.
type Mode ¶
type Mode string
Mode states how a patch places its elements.
const ( // ModeOuter replaces the element that the selector names. ModeOuter Mode = "outer" // ModeInner replaces the children of the element. ModeInner Mode = "inner" // ModeReplace replaces the element and keeps no attribute. ModeReplace Mode = "replace" // ModePrepend puts the elements before the first child. ModePrepend Mode = "prepend" // ModeAppend puts the elements after the last child. ModeAppend Mode = "append" // ModeBefore puts the elements before the element. ModeBefore Mode = "before" // ModeAfter puts the elements after the element. ModeAfter Mode = "after" // ModeRemove removes the element that the selector names. ModeRemove Mode = "remove" )
The modes of an element patch. The default is outer, which the frame omits.
type Option ¶
type Option func(*patch)
Option configures one element patch.
func WithSelector ¶
WithSelector names the element that the patch changes. An empty selector leaves the placement to the identifier of the elements.
func WithViewTransition ¶
func WithViewTransition() Option
WithViewTransition asks the browser for a view transition.
type SignalOption ¶
type SignalOption func(*signals)
SignalOption configures one signal patch.
func WithOnlyIfMissing ¶
func WithOnlyIfMissing() SignalOption
WithOnlyIfMissing keeps a signal that the store already holds.
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream writes Datastar frames to one client.
func (*Stream) Done ¶
func (s *Stream) Done() <-chan struct{}
Done returns a channel that closes when the client disconnects.
select {
case <-s.Done():
return nil
case row := <-rows:
return s.PatchElements(rows.View(row))
}
func (*Stream) ExecuteScript ¶
ExecuteScript runs a script in the browser.
Version 1.0 of the Datastar specification carries no execute script event. The script becomes a script element that the patch appends to the body, and the effect attribute removes the element after it runs.
func (*Stream) PatchElements ¶
PatchElements renders a component and patches it into the document.
The component is a templ component or any other view.Component, so a page and a patch share one template.
func (*Stream) PatchHTML ¶
PatchHTML patches markup into the document. PatchElements renders a component and calls it.
func (*Stream) PatchSignals ¶
func (s *Stream) PatchSignals(v any, opts ...SignalOption) error
PatchSignals encodes v as JSON and patches it into the signal store.
return s.PatchSignals(map[string]any{"count": n})
func (*Stream) RemoveElements ¶
RemoveElements removes every element that the selector names.