StarView.Page.Helpers (star_view v0.7.0)

Copy Markdown View Source

Template and handler helpers imported by use StarView.Page.

  • event/1,2 — Datastar action expression targeting the page's own _event route, resolved client-side via location.pathname.
  • connect/0,1 — Datastar action expression opening the page's SSE stream.
  • patch/3,4 — render a function component into a patch_elements call.

Summary

Functions

Builds the stream-connect expression for data-init / data-on:online__window.

Builds a page-local Datastar action expression.

Renders a function component and pipes it to StarView.Elements.patch/3.

Functions

connect(opts \\ [])

Builds the stream-connect expression for data-init / data-on:online__window.

connect()
# POST to the validated current pathname, using the client's default retry policy

connect(retry: :always)
# Reconnect after successful read-stream closures too

connect(include_search: true)
# Include the current query string

Options

  • :opts — override the options object (default "{retryMaxCount: Infinity}")
  • :retry — :auto | :always | :error | :never. Opting into a retry mode uses a default maximum of 64 consecutive failures (:never uses zero) unless :opts sets a different maximum. The typed mode overrides retry in a custom object expression.

  • :include_search — append location.search so query params reach handle_connect (pages whose render depends on them, e.g. ?step=).

Always emits @post — StarView streams connect over POST. :always reconnects even after a deliberate server halt. Use it for live resources that reconcile an authorized snapshot on every connection, not mutation requests. The default remains unchanged for existing pages.

event(name, opts \\ [])

Builds a page-local Datastar action expression.

event("increment")
# Validated local pathname + encoded /_event/increment segment

event("remove", verb: :delete)
# Requires event_methods: [:post, :delete] on the page route

The URL is computed in the browser, so path params (workspace slugs, ids) need no server-side threading. Event names become a single URL path segment and are percent-encoded as literal data. Empty names and exact dot segments raise.

Trailing slashes in the path are stripped client-side so pages mounted at "/" or visited with a trailing slash don't produce protocol-relative ("//") or double-slash URLs.

Options

  • :verb — :get | :post | :put | :patch | :delete (default :post)

  • :opts — raw JS object string appended as the action's options, e.g. "{retryMaxCount: 5}". Trusted developer input only — it is emitted verbatim into the expression.

GET events are not CSRF-protected

Plug.CSRFProtection does not check tokens on GET requests, so verb: :get events can be triggered cross-site. Use :get only for side-effect-free reads.

patch(conn, component, assigns, opts \\ [])

Renders a function component and pipes it to StarView.Elements.patch/3.

conn |> patch(&history/1, value: count)
conn |> patch(&item_card/1, [item: item], selector: "#row-1", mode: :outer)

With no :selector, Datastar matches elements by their id attribute, so the component's root element must carry one.