ExLiveUrl (ExLiveUrl v0.2.0)

ExLiveUrl is just some simple Phoenix LiveView lifecycle hooks and helper functions. It helps you store the live view's current query params and path in your assigns. Additionally, it exposes ways to work with those values both synchronously (only from the root live view) and asynchronously (from anywhere).

Installation

You can install ExLiveUrl like so:

defp deps do
  [
    {:ex_live_url, "~> 0.2.0"}
  ]
end

To use ExLiveUrl you will need to call Phoenix.LiveView.on_mount/1 with the module, ExLiveUrl in your live view. For example:

defmodule YourLiveView do
  use Phoenix.LiveView

  on_mount ExLiveUrl

  # your live view implementation
end

Example

A common use case for url state in live views is to store sorting and filtering information. Here's a working example of how you can implement such a use case with ExLiveUrl.

iex> defmodule Example.SortControl do
...>   use Phoenix.LiveComponent
...>
...>   @impl Phoenix.LiveComponent
...>   def render(assigns) do
...>     ~H"""
...>     <button phx-click="toggle" phx-target={@myself}>
...>       <%= @direction || "sort" %>
...>     </button>
...>     """
...>   end
...>
...>   @impl Phoenix.LiveComponent
...>   def handle_event("toggle", _payload, socket) do
...>     :ok = ExLiveUrl.send_operation(fn url ->
...>       ExLiveUrl.Operation.push_patch(to: ExLiveUrl.Url.with_params(url, fn params ->
...>         Map.update(params, "direction", "asc", fn
...>           "asc" -> "desc"
...>           "desc" -> "asc"
...>         end)
...>       end))
...>     end)
...>
...>     {:noreply, socket}
...>   end
...> end

iex> defmodule Example.LiveView do
...>   use Phoenix.LiveView
...>   on_mount ExLiveUrl
...>
...>   @impl Phoenix.LiveView
...>   def render(assigns) do
...>     ~H"""
...>     <.live_component module={Example.SortControl} id="Example.SortControl" direction={@direction} />
...>     <p :for={name <- @names}><%= name %></p>
...>     """
...>   end
...>
...>   @impl Phoenix.LiveView
...>   def mount(_params, _session, socket) do
...>     {:ok, assign(socket, :names, ["John", "Jimmy", "Jack", "Joe"])}
...>   end
...>
...>   @impl Phoenix.LiveView
...>   def handle_params(params, _uri, socket) do
...>     {:ok,
...>      socket
...>      |> assign(:direction, params["direction"])
...>      |> update(
...>        :names,
...>        fn names ->
...>          case params["direction"] do
...>            "desc" -> Enum.sort(names, fn name_1, name_2 -> name_1 <= name_2 end)
...>            "asc" -> Enum.sort(names, fn name_1, name_2 -> name_1 >= name_2 end)
...>            nil -> names
...>          end
...>        end
...>      )}
...>   end
...> end

Link to this section Summary

Functions

Tip: This function may only be called with the root live view's socket. If you need to, for example, call this from a live component, you should use send_operation/2.

A special case of send_operation/2 which uses self() as the given pid.

Asynchronously build and apply an operation. The build function takes the current ExLiveUrl.Url as an argument and must return an ExLiveUrl.Operation. The given pid must be a root live view.

Link to this section Functions

Link to this function

apply_operation(socket, operation)

(since 0.2.0)

Tip: This function may only be called with the root live view's socket. If you need to, for example, call this from a live component, you should use send_operation/2.

Synchronously build and apply an operation. The build function takes the current ExLiveUrl.Url as an argument and must return an ExLiveUrl.Operation. The given pid must be a root live view.

This is an alias for ExLiveUrl.Operation.apply/2.

Link to this function

send_operation(fun)

(since 0.2.0)
@spec send_operation((ExLiveUrl.Url.t() -> ExLiveUrl.Operation.t())) :: :ok

A special case of send_operation/2 which uses self() as the given pid.

Link to this function

send_operation(pid, fun)

(since 0.2.0)
@spec send_operation(pid(), (ExLiveUrl.Url.t() -> ExLiveUrl.Operation.t())) :: :ok

Asynchronously build and apply an operation. The build function takes the current ExLiveUrl.Url as an argument and must return an ExLiveUrl.Operation. The given pid must be a root live view.