Phoenix.LiveView.Router

Извлекает flash-сообщения LiveView и объединяет их с flash-сообщениями контроллера.

Заменяет стандартный plug :fetch_flash, используемый в Phoenix.Router.

Примеры

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

  pipeline :browser do
    ...
    plug :fetch_live_flash
  end
  ...
end

Определяет маршрут LiveView.

Маршрут к LiveView можно определить с помощью макроса live, указав путь и имя LiveView:

live "/thermostat", ThermostatLive

Чтобы перейти к этому маршруту в приложении, можно использовать Phoenix.VerifiedRoutes:

push_navigate(socket, to: ~p"/thermostat")
push_patch(socket, to: ~p"/thermostat?page=#{page}")

Действия и live-навигация

Часто LiveView имеет несколько состояний и несколько URL-адресов. Например, можно создать LiveView, который отображает список всех статей веб-приложения. Для каждой статьи есть кнопка «Редактировать», при нажатии на которую на той же странице открывается модальное окно для редактирования статьи. В таких случаях рекомендуется использовать live-навигацию: при нажатии кнопки «Редактировать» URL меняется на "/articles/1/edit", хотя вы по-прежнему находитесь в том же LiveView. Аналогичным образом можно добавить кнопку «Создать», открывающую модальное окно для создания новой записи, и отразить это в URL как "/articles/new".

Чтобы упростить определение текущего «действия» LiveView, при определении LiveView можно также передать параметр action:

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

Текущее действие всегда доступно внутри LiveView в виде assign @live_action, который можно использовать для отображения LiveComponent:

<.live_component :if={@live_action == :new} module={MyAppWeb.ArticleLive.FormComponent} id="form" />

Или его можно использовать, чтобы показывать или скрывать части шаблона:

{if @live_action == :edit, do: render("form.html", user: @user)}

Обратите внимание, что @live_action будет nil, если в определении маршрута не указано действие.

Параметры

• :container — необязательный кортеж с HTML-тегом и DOM-атрибутами контейнера LiveView. Например: {:li, style: "color: blue;"}. Дополнительные сведения и примеры см. в разделе Phoenix.Component.live_render/3.

• :as — необязательная настройка именованного helper. По умолчанию используется :live, если LiveView не имеет действий, и имя LiveView, если действия есть.

• :metadata — карта необязательных метаданных для событий telemetry и информации о маршруте, например: %{route_name: :foo, access: :user}. Эти данные можно получить, вызвав Phoenix.Router.route_info/4 с uri из callback-функции handle_params. Это позволяет настроить LiveView, который может вызываться из разных маршрутов.

• :private — необязательная карта приватных данных, которые нужно добавить в plug connection, например: %{route_name: :foo, access: :user}. Эти данные будут доступны внутри conn.private в plug-функциях.

• :warn_on_verify — логическое значение, определяющее, вызывает ли совпадение с этим маршрутом предупреждение о несовпавшем маршруте для Phoenix.VerifiedRoutes. Может быть полезно исключить из проверки маршрутов определение маршрута, которое в противном случае соответствовало бы любому маршруту. По умолчанию используется false.

Примеры

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, container: {:main, class: "row"}
  end
end

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

Определяет live-сессию для live-перенаправлений внутри группы live-маршрутов.

live_session/3 позволяют маршрутам, определённым с помощью live/4, поддерживать перенаправления navigate от клиента, выполняя навигацию только через существующее websocket-соединение. Благодаря этому live-маршруты, определённые в роутере, могут монтировать новый корневой LiveView без дополнительных HTTP-запросов к серверу. Для обратной совместимости все live-маршруты, определённые вне какой-либо live-сессии, считаются частью одной безымянной live-сессии.

Вопросы безопасности

В обычном веб-приложении проверка аутентификации и авторизации выполняется при каждом запросе. Поскольку LiveView запускаются как обычный HTTP-запрос, они используют ту же логику аутентификации, что и обычные запросы, через plug-функции. После аутентификации пользователя обычно проверяются сессии в callback-функции mount. Правила авторизации обычно проверяются при mount (например, разрешено ли пользователю просматривать эту страницу?) и также при handle_event (разрешено ли пользователю удалить этот элемент?). Авторизация при монтировании важна, потому что navigate не проходят через конвейер plug.

live_session можно использовать для разграничения групп LiveView. Перенаправление между live_session всегда приводит к полной перезагрузке страницы и установлению нового соединения LiveView. Это полезно, если для LiveView требуются разные стратегии аутентификации или если они используют разные корневые макеты (корневой макет не обновляется при live-перенаправлениях).

Подробное описание, а также общие рекомендации по аутентификации, авторизации и другим вопросам см. в руководстве по модели безопасности.

Параметры

• :session — необязательная дополнительная карта сессии или кортеж MFA, который будет объединён с сессией LiveView. Например, %{"admin" => true} или {MyMod, :session, []}. Для MFA вызывается функция, а структура Plug.Conn добавляется в начало списка аргументов.

• :root_layout — необязательный кортеж корневого макета для первоначального HTTP-рендеринга, переопределяющий корневой макет, заданный в роутере.

• :on_mount — необязательный список хуков, которые будут привязаны к жизненному циклу монтирования каждого LiveView в сессии. См. Phoenix.LiveView.on_mount/1. Можно также передать одно значение.

• :layout — необязательный макет, в котором будет отображаться LiveView. Этот параметр переопределяет макет через use Phoenix.LiveView. Его можно переопределить внутри LiveView, вернув {:ok, socket, layout: ...} из callback-функции mount.

Примеры

scope "/", MyAppWeb do
  pipe_through :browser

  live_session :default do
    live "/feed", FeedLive, :index
    live "/status", StatusLive, :index
    live "/status/:id", StatusLive, :show
  end

  live_session :admin, on_mount: MyAppWeb.AdminLiveAuth do
    live "/admin", AdminDashboardLive, :index
    live "/admin/posts", AdminPostLive, :index
  end
end

В приведённом выше примере определены две live-сессии. Live-навигация между представлениями в разных сессиях невозможна и всегда требует полной перезагрузки страницы. Это важно в данном примере, поскольку для live-сессии :admin требуется аутентификация, заданная с помощью on_mount: MyAppWeb.AdminLiveAuth, которая не нужна другим LiveView.

Если у вас есть обычные HTTP-маршруты (через get, post и т. д.) и маршруты live, необходимо применять одинаковые правила аутентификации и авторизации для обоих типов. Например, если добавить маршрут get "/admin/health", нужно создать собственный plug, который применяет те же правила аутентификации и авторизации, что и MyAppWeb.AdminLiveAuth, а затем подключить его в конвейер:

scope "/" do
  # Regular routes
  pipe_through [MyAppWeb.AdminPlugAuth]
  get "/admin/health", AdminHealthController, :index

  # Live routes
  live_session :admin, on_mount: MyAppWeb.AdminLiveAuth do
    live "/admin", AdminDashboardLive, :index
    live "/admin/posts", AdminPostLive, :index
  end
end