Phoenix.LiveView.Router
Provides LiveView routing for Phoenix routers.
Summary
Functions
- fetch_live_flash(conn, _)
-
Fetches the LiveView and merges with the controller flash.
- live(path, live_view, action \\ nil, opts \\ [])
-
Defines a LiveView route.
Functions
fetch_live_flash(conn, _)
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
live(path, live_view, action \\ nil, opts \\ [])
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 this to be reflected 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/:id/edit", ArticleLive.Index, :edit
When an action is given, the generated route helpers are named after the LiveView itself (in the same way as for 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, that can be used to render a LiveComponent:
<%= if @live_action == :new do %> <%= live_component @socket, MyAppWeb.ArticleLive.FormComponent %> <% end %>
Or can be used to show or hide parts of the template:
<%= if @live_action == :edit do %> <%= render("form.html", user: @user) %> <% end %>
Note that @live_action
will be nil
if no action is given on the route definition.
Options
-
:session
- a map to be merged into the session, for example:%{"my_key" => 123}
. The map keys must be strings.Can also be a "MFA" (module, function, arguments) tuple. That function will receive the connection and should return a map (with string keys) to be merged into the session. For example,
{MyModule, :my_function, []}
meansMyModule.my_function(conn)
is called. :layout
- an optional tuple to specify the rendering layout for the LiveView. If set, this option will replace the current root layout.:container
- an optional tuple for the HTML tag and DOM attributes to be used for the LiveView container. For example:{:li, style: "color: blue;"}
. SeePhoenix.LiveView.Helpers.live_render/3
for more information and examples.:as
- optionally configures the named helper. Defaults to:live
when using a LiveView without actions or defaults 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"
© 2018 Chris McCord
Licensed under the MIT License.
https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.Router.html