docs: document hooks and JS commands in dead views#4246
Conversation
|
As per @josevalim, we don't refer to regular views as dead views. Therefore, I don't think we should make this as prominent. So instead of
rather
and then in the headings just say "regular view" instead of "dead view"? We should also link back to the Phoenix docs (https://hexdocs.pm/phoenix/controllers.html#rendering). |
| * **`phx-mounted`** — runs as soon as `liveSocket.connect()` is executed | ||
| (see [Bindings](bindings.md#dom-patching)). |
There was a problem hiding this comment.
Not 100% correct, as we also wait for the document to be ready (i.e. DOMContentLoaded)
phoenix_live_view/assets/js/phoenix_live_view/live_socket.ts
Lines 513 to 519 in 5824e9a
What
Adds a dedicated, searchable section to the JavaScript interoperability guide covering how
phx-hook,phx-mounted, and client-sidePhoenix.LiveView.JScommands behave on regular pages that are not LiveViews (dead views).Why
The term dead view is used broadly across the technical surface — in the code, in the CHANGELOG ("Add dead view support for hooks" / "Add dead view support for JS commands", v0.18.0), and commonly in conversation — but it appears nowhere in the docs. That leaves the term, and the capability behind it, unclear to users who encounter it elsewhere and have nothing to search for.
The feature itself (hooks and JS commands outside a LiveView) shipped in v0.18.0 yet was only hinted at by a single one-line note in the hook lifecycle list that never named "dead view" — so it's effectively undiscoverable, by people and AI assistants alike.
Changes
guides/client/js-interop.md, introducing the term dead view (with synonyms — dead render / static page / outside of a LiveView) and splitting behavior into what works vs. what doesn't:phx-hook(mountedonly),phx-mounted,phx-click+ purely client-sideJScommands.JS.navigate/JS.patch: live navigation when a LiveView is present, otherwise a full-page browser navigation fallback.JS.push, form bindings (phx-change,phx-submit),phx-connected/phx-disconnected.phx-mountedandphx-connected/phx-disconnectednotes inguides/client/bindings.md.Docs-only; no code changes.