Subscriptions from scratch
Say you are building a video player. You want different controls when the
video goes fullscreen. The browser fires a
fullscreenchange
event, but did it just enter or leave fullscreen? The event does not say. You
have to read document.fullscreenElement. You also have to remove the listener
when the app no longer needs fullscreen updates.
off_topic helps you manage this lifecycle. It asks your
subscriptions function which listeners should be active, starts new ones,
and cleans up those you stop returning, all while sending their messages through
update as usual. The built-in window_size subscription works this way too:
it reads the current value, listens for changes, and cleans up afterward.
Let’s write a fullscreen subscription with from.
Start with the browser API
We need one JavaScript function that reports the current state, attaches a listener, and returns a function to remove it. Gleam declares that function as an external:
// src/my_app/browser.gleam
@external(javascript, "./browser.mjs", "onFullscreenChange")
pub fn on_fullscreen_change(report: fn(Bool) -> Nil) -> fn() -> Nil
Here is the JavaScript next to it:
// src/my_app/browser.mjs
export function onFullscreenChange(report) {
const send = () => report(document.fullscreenElement !== null);
document.addEventListener("fullscreenchange", send);
send();
return () => document.removeEventListener("fullscreenchange", send);
}
The call to send() is easy to overlook. If this subscription starts while an
element is already fullscreen, waiting for the next event would leave the
model with the wrong value. Many useful subscriptions follow this pattern:
send the current value first, then keep it up to date.
Let off_topic manage its lifetime
from takes a list of dependencies and a setup callback, which then can register
any listeners and must return a cleanup function. Our JavaScript function already
has exactly that shape:
// src/my_app/subscriptions.gleam
import my_app/browser
import off_topic.{type Subscription}
pub fn fullscreen(send: fn(Bool) -> message) -> Subscription(message) {
use dispatch <- off_topic.from(watching: [off_topic.dep("my-app/fullscreen")])
browser.on_fullscreen_change(fn(active) { dispatch(send(active)) })
}
Return fullscreen(FullscreenChanged) from your app’s subscriptions
callback to then subscribe to the current fullscreen state! When off_topic
starts it, the callback calls the on_fullscreen_change FFI function, and the
function it returns becomes the cleanup for the subscription.
When does it restart?
After an update, off_topic compares the new subscriptions with the ones already running. By default, it matches them structurally, comparing them by position in their batch, before comparing their dependencies. If they all turn out equal, the dependency keeps running, while different ones cause off_topic to run cleanup and setup again.
We pass "my-app/fullscreen" as an identifier dependency in this subscription.
That matters because off_topic does not compare the setup functions themselves, since they
might close over other data as well. If a different custom subscription takes this
position with the same dependency list, off_topic would still the old listener,
so having a dependency that is for sure different solves this problem.
Typically, you add a dependency for any input that should reopen the listener. A subscription to a user-specific event stream, for example, needs the user ID:
watching: [
off_topic.dep("my-app/user-events"),
off_topic.dep(user_id),
]
A changed user ID then closes the old stream and opens the new one. The
watching helper adds dependencies to an existing subscription when you need
the same behavior with a built-in.
When the root element matters
from is enough for browser APIs on document or window. If setup needs
the Lustre root element, use element. Its callback receives both dispatch
and the root as a Dynamic value. It runs before paint, when the root is in
the DOM. The same cleanup rule applies: a ResizeObserver, for example,
should return a function that calls disconnect(). The built-in
element_size subscription shows this pattern.
The fullscreen example runs in a browser app. Server components need a
browser-side handler registered with remote; see
Server components.