StarView.Controller (star_view v0.3.4)

Copy Markdown

Phoenix controller helpers for StarView.

Use use StarView from your web module after use Phoenix.Controller has been applied:

def controller do
  quote do
    use Phoenix.Controller, formats: [:html]
    use StarView
  end
end

Controllers implement StarView:

@impl StarView
def handle_event("increment", signals, conn), do: ...

assign/3 vs signal/3

  • assign/3 sets a Plug connection assign. Function components can read it via @key, but it is never sent to the browser.
  • signal/3 does assign/3 and sends the value to the browser when the connection is already an SSE response. Before SSE starts, it records the value for init_signals/1.

Summary

Functions

extract_signals(conn)

Extracts tracked signal keys, values, and per-signal options.

flush_signals(conn)

Flushes tracked pre-start signals as Datastar signal patch events.

init_signals(conn)

Returns the tracked signal map as JSON for data-signals.

patch_element(conn, component_or_html, opts \\ [])

Patches a rendered component or HTML value against current assigns.

signal(conn, key, value, opts \\ [])

Assigns a value and exposes it as a Datastar signal.

Functions

extract_signals(conn)

@spec extract_signals(Plug.Conn.t()) :: [{atom(), term(), keyword()}]

Extracts tracked signal keys, values, and per-signal options.

flush_signals(conn)

@spec flush_signals(Plug.Conn.t()) :: Plug.Conn.t()

Flushes tracked pre-start signals as Datastar signal patch events.

This is retained for manual flows that call signal/4 before starting SSE. Controllers dispatched through StarView.Dispatch patch signals immediately and do not need a final flush.

init_signals(conn)

@spec init_signals(Plug.Conn.t()) :: String.t() | nil

Returns the tracked signal map as JSON for data-signals.

patch_element(conn, component_or_html, opts \\ [])

@spec patch_element(Plug.Conn.t(), (map() -> term()) | term(), keyword()) ::
  Plug.Conn.t()

Patches a rendered component or HTML value against current assigns.

signal(conn, key, value, opts \\ [])

@spec signal(Plug.Conn.t(), atom(), term(), keyword()) :: Plug.Conn.t()

Assigns a value and exposes it as a Datastar signal.

Before the SSE response starts, the signal is recorded for init_signals/1. During an SSE response, the signal is patched immediately so the browser sees updates in the same order as the server pipeline.