add auto_connect option to LiveView mount options

to specify that a LiveView should not automatically connect
on dead render. When navigated to and there's already a connection
established, this option has no effect.

See https://elixirforum.com/t/liveview-feature-to-cancel-second-render/67770

Author: SteffenDE

assets/js/phoenix_live_view/constants.js

@@ -31,6 +31,7 @@ export const PHX_ERROR_CLASS = "phx-error"
 export const PHX_CLIENT_ERROR_CLASS = "phx-client-error"
 export const PHX_SERVER_ERROR_CLASS = "phx-server-error"
 export const PHX_PARENT_ID = "data-phx-parent-id"
+export const PHX_AUTO_CONNECT = "data-phx-auto-connect"
 export const PHX_MAIN = "data-phx-main"
 export const PHX_ROOT_ID = "data-phx-root-id"
 export const PHX_VIEWPORT_TOP = "viewport-top"

assets/js/phoenix_live_view/live_socket.js

@@ -93,6 +93,7 @@ import {
   PHX_PARENT_ID,
   PHX_VIEW_SELECTOR,
   PHX_ROOT_ID,
+  PHX_AUTO_CONNECT,
   PHX_THROTTLE,
   PHX_TRACK_UPLOADS,
   PHX_SESSION,
@@ -372,7 +373,7 @@ export default class LiveSocket {
 
   joinRootViews(){
     let rootsFound = false
-    DOM.all(document, `${PHX_VIEW_SELECTOR}:not([${PHX_PARENT_ID}])`, rootEl => {
+    DOM.all(document, `${PHX_VIEW_SELECTOR}:not([${PHX_PARENT_ID}]):not([${PHX_AUTO_CONNECT}="false"])`, rootEl => {
       if(!this.getRootById(rootEl.id)){
         let view = this.newRootView(rootEl)
         // stickies cannot be mounted at the router and therefore should not

lib/phoenix_live_view.ex

@@ -217,6 +217,13 @@ defmodule Phoenix.LiveView do
       this option will override any layout previously set via
       `Phoenix.LiveView.Router.live_session/2` or on `use Phoenix.LiveView`
 
+    * `:auto_connect` - if false, instructs the LiveView JavaScript client
+      to not automatically connect to the server on dead render.
+      This is useful when you have a static page that does not require
+      any connected functionality, but should render over the existing
+      connection when navigating from an already connected LiveView.
+      Defaults to `true`.
+
   """
   @callback mount(
               params :: unsigned_params() | :not_mounted_at_router,

lib/phoenix_live_view/static.ex

@@ -161,6 +161,12 @@ defmodule Phoenix.LiveView.Static do
 
         data_attrs = if(router, do: [phx_main: true], else: []) ++ data_attrs
 
+        data_attrs =
+          if(not Map.get(socket.private, :auto_connect, true),
+            do: [phx_auto_connect: "false"],
+            else: []
+          ) ++ data_attrs
+
         attrs = [
           {:id, socket.id},
           {:data, data_attrs}

lib/phoenix_live_view/utils.ex

@@ -6,7 +6,7 @@ defmodule Phoenix.LiveView.Utils do
   alias Phoenix.LiveView.{Socket, Lifecycle}
 
   # All available mount options
-  @mount_opts [:temporary_assigns, :layout]
+  @mount_opts [:temporary_assigns, :layout, :auto_connect]
 
   @max_flash_age :timer.seconds(60)
 
@@ -437,6 +437,14 @@ defmodule Phoenix.LiveView.Utils do
     }
   end
 
+  defp handle_mount_option(%Socket{} = socket, :auto_connect, value) do
+    if not is_boolean(value) do
+      raise "the :auto_connect mount option must be a boolean, got: #{inspect(value)}"
+    end
+
+    put_in(socket.private[:auto_connect], value)
+  end
+
   @doc """
   Calls the `handle_params/3` callback, and returns the result.
 

test/e2e/support/lifecycle.ex

@@ -0,0 +1,22 @@
+defmodule Phoenix.LiveViewTest.E2E.LifecycleLive do
+  use Phoenix.LiveView
+
+  @impl Phoenix.LiveView
+  def mount(params, _session, socket) do
+    auto_connect = case params do
+      %{"auto_connect" => "false"} -> false
+      _ -> true
+    end
+
+    {:ok, socket, auto_connect: auto_connect}
+  end
+
+  @impl Phoenix.LiveView
+  def render(assigns) do
+    ~H"""
+    <div>Hello!</div>
+    <.link navigate="/lifecycle">Navigate to self (auto_connect=true)</.link>
+    <.link navigate="/lifecycle?auto_connect=false">Navigate to self (auto_connect=false)</.link>
+    """
+  end
+end

test/e2e/test_helper.exs

@@ -139,6 +139,7 @@ defmodule Phoenix.LiveViewTest.E2E.Router do
       live "/form/stream", E2E.FormStreamLive
       live "/js", E2E.JsLive
       live "/select", E2E.SelectLive
+      live "/lifecycle", E2E.LifecycleLive
     end
 
     scope "/issues", Phoenix.LiveViewTest.E2E do

test/e2e/tests/lifecycle.spec.js

@@ -0,0 +1,57 @@
+const {test, expect} = require("../test-fixtures")
+const {syncLV} = require("../utils")
+
+test.describe("auto_connect", () => {
+  let webSocketEvents = []
+  let networkEvents = []
+  let consoleMessages = []
+
+  test.beforeEach(async ({page}) => {
+    networkEvents = []
+    webSocketEvents = []
+    consoleMessages = []
+
+    page.on("request", request => networkEvents.push({method: request.method(), url: request.url()}))
+
+    page.on("websocket", ws => {
+      ws.on("framesent", event => webSocketEvents.push({type: "sent", payload: event.payload}))
+      ws.on("framereceived", event => webSocketEvents.push({type: "received", payload: event.payload}))
+      ws.on("close", () => webSocketEvents.push({type: "close"}))
+    })
+
+    page.on("console", msg => consoleMessages.push(msg.text()))
+  })
+
+  test("connects by default", async ({page}) => {
+    await page.goto("/lifecycle")
+    await syncLV(page)
+
+    expect(webSocketEvents).toHaveLength(2)
+  })
+
+  test("does not connect when auto_connect is false", async ({page}) => {
+    await page.goto("/lifecycle?auto_connect=true")
+    // eslint-disable-next-line playwright/no-networkidle
+    await page.waitForLoadState("networkidle")
+    expect(webSocketEvents).toHaveLength(0)
+  })
+
+  test("connects when navigating to a view with auto_connect=true", async ({page}) => {
+    await page.goto("/lifecycle?auto_connect=false")
+    // eslint-disable-next-line playwright/no-networkidle
+    await page.waitForLoadState("networkidle")
+    expect(webSocketEvents).toHaveLength(0)
+    await page.getByRole("link", {name: "Navigate to self (auto_connect=true)"}).click()
+    await syncLV(page)
+    expect(webSocketEvents).toHaveLength(2)
+  })
+  
+  test("stays connected when navigating to a view with auto_connect=false", async ({page}) => {
+    await page.goto("/lifecycle")
+    await syncLV(page)
+    expect(webSocketEvents).toHaveLength(2)
+    await page.getByRole("link", {name: "Navigate to self (auto_connect=false)"}).click()
+    await syncLV(page)
+    expect(webSocketEvents).toHaveLength(7)
+  })
+})