phoenix_live_view v0.11.0 Phoenix.LiveView.Router View Source

Provides LiveView routing for Phoenix routers.

Link to this section Summary

Functions

Fetches the LiveView and merges with the controller flash.

Link to this section Functions

Link to this function

fetch_live_flash(conn, _)

View Source

Fetches the LiveView and merges with the controller flash.

Replaces the default :fetch_flash plug used by Phoenix.Router.

Examples

defmodule AppWeb.Router do
  use LiveGenWeb, :router
  import Phoenix.LiveView.Router

  pipeline :browser do
    ...
    plug :fetch_live_flash
  end
  ...
end
Link to this macro

live(path, live_view, action \\ nil, opts \\ [])

View Source (macro)

Defines a LiveView route.

A LiveView can be routed to by using the live macro with a path and the name of the LiveView:

live "/thermostat", ThermostatLive

By default, you can generate a route to this LiveView by using the live_path helper:

live_path(@socket, ThermostatLive)

Actions and live navigation

It is common for a LiveView to have multiple states and multiple URLs. For example, you can have a single LiveView that lists all articles on your web app. For each article there is an "Edit" button which, when pressed, opens up a modal on the same page to edit the article. It is a best practice to use live navigation in those cases, so when you click edit, the URL changes to "/articles/1/edit", even though you are still within the same LiveView. Similarly, you may also want to show a "New" button, which opens up the modal to create new entries, and you want that to reflect in the URL as "/articles/new".

In order to make it easier to recognize the current "action" your LiveView is on, you can pass the action option when defining LiveViews too:

live "/articles", ArticleLive.Index, :index
live "/articles/new", ArticleLive.Index, :new
live "/articles/1/edit", ArticleLive.Index, :edit

When an action is given, the generated route helpers are named after the LiveView itself (the same as in a controller). For the example above, we will have:

article_index_path(@socket, :index)
article_index_path(@socket, :new)
article_index_path(@socket, :edit, 123)

The current action will always be available inside the LiveView as the @live_action assign. @live_action will be nil if no action is given on the route definition.

Options

  • :session - a map of strings keys and values to be merged into the session. Maybe also be a "MFArgs" tuple that will receive the connection to compute the session.

  • :layout - the optional tuple for specifying a layout to render the LiveView. If set, this option will replace the current root layout.

  • :container - the optional tuple for the HTML tag and DOM attributes to be used for the LiveView container. For example: {:li, style: "color: blue;"}. See Phoenix.LiveView.live_render/3 for more information on examples.

  • :as - optionally configures the named helper. Defaults to :live when using a LiveView without actions or default to the LiveView name when using actions.

  • :metadata - a map to optional feed metadata used on telemetry events and route info for example: %{route_name: :foo, access: :user}.

Examples

defmodule MyApp.Router
  use Phoenix.Router
  import Phoenix.LiveView.Router

  scope "/", MyApp do
    pipe_through [:browser]

    live "/thermostat", ThermostatLive
    live "/clock", ClockLive
    live "/dashboard", DashboardLive, layout: {MyApp.AlternativeView, "app.html"}
  end
end

iex> MyApp.Router.Helpers.live_path(MyApp.Endpoint, MyApp.ThermostatLive)
"/thermostat"