DocsRealtime

Live views

Views rendered on the server whose state stays there; the browser sends events and gets back only what changed.

A live view keeps its state on the server and renders it there. The browser sends what the user does, and gets back only the values that changed, often a few bytes. A view is a file in views/:

views/counter.js
export const rule = "@request.auth.id != null";

export function mount(ctx) {
  return { count: 0 };
}

export function render(state, html) {
  return html`<button sluurp-click="bump">Clicked ${state.count} times</button>`;
}

export function handle(event, payload, state, ctx) {
  if (event === "bump") return { ...state, count: state.count + 1 };
  return state;
}
  • rule: who may open it, in the rules language.
  • mount: answers the first state; ctx has the user who opened the view.
  • render: renders the state with the html tag.
  • handle: takes an event and answers the next state.

Use a live view when the server should own the state, such as a register, a dashboard or a checkout. It isn’t meant for editing together: if two people type in the same field, the last write wins.

Show a view on a page

To show a view, mount it on an element:

app.ts
import { mount } from "@sluurp/client/live";
await mount("#counter", "counter");

Attributes bind the page’s events to the view’s:

<button sluurp-click="bump">+1</button>
<input sluurp-input="search" name="q">
<form sluurp-submit="save">…</form>

The payload holds the element’s value, a form’s fields, and any sluurp-value-* attributes. To leave an element’s children alone across updates, such as a widget the browser draws, add sluurp-ignore.

Why so little is sent

JavaScript already splits a tagged html template into fixed strings and the values between them. Sluurp compares only the values between renders, and sends only those that changed. A counter going from 41 to 42 sends 42.

Sign-in is the browser client’s, so a view sees the same user as the REST API does.

View as Markdown