Cartograph - E2E Query Param Patching for LiveView

I created this library to handle relative query patching for Phoenix live patch and navigate events.

This is based on the discussion in Add `:params` opt to JS.patch and JS.navigate, and opt to merge `phx-value-*` and @steffend ‘s feedback on this LiveView PR: WIP: Relative Query Patching by GrammAcc · Pull Request #4067 · phoenixframework/phoenix_live_view · GitHub .

Unlike that PR, this library handles all of the param parsing server-side instead of in the client-side JS.

The library provides Cartograph.LiveViewParams which can be used by a LiveView module to add the event handlers for the library’s relative query patching events.

The main api is in the Cartograph.Component module, which provides a cartograph_patch/1 and cartograph_navigate/2 function. Both functions accept a :query keyword list of operations to apply to the current page’s query params.

For example: cartograph_patch(query: [merge: %{page_no: 2}]) will send a live patch event to the server with the current url and params but with the page_no query param set to 2.

There are several other operations that can be composed together for pretty much any kind of relative query alteration.

This makes it easier to maintain query params in the URL with pure function components that might otherwise clobber each other’s state. For example, a reusable pagination widget and a reusable filters widget.

Another use-case that was discussed in the linked thread and PR is having the complete URL pre-computed on the server so that the user can right-click and copy the link in the browser. This use-case is supported by the parse_patch/2 and parse_navigate/2 functions in the Cartograph.Component module.

These functions take a url and the same :query keyword options and parse them together into a string suitable to be used in LiveView’s patch or navigate respectively. This enables the use-case described above with .link components:

<.link patch={parse_patch(@cartograph_uri, query: [merge: %{page_no: @page_no - 1}])}>Prev</.link>

The @cartograph_uri assign is added by the library to maintain the current URI from the latest call to handle_params/3, so it is always accessible in the LiveView for relative navigation.

The Cartograph.LiveViewParams module also provides some conveniences for reducing boilerplate when parsing query params in the LiveView.

We can declare a @cartograph_parser module attribute that registers a 3-arity function to the handle params lifecycle hook to take care of most of the logic in handle_params/3:

@cartograph_parser [
  handler: &__MODULE__.parse_params/3,
  keys: [:page_no, :page_size],
]

def parse_params(socket, %{"page_no" => page_no}, :page_no) do
  assign(socket, :page_no, page_no)
end

def parse_params(socket, %{}, :page_no), do: assign(socket, :page_no, 1)

def parse_params(socket, %{"page_size" => page_size}, :page_size) do
  assign(socket, :page_size, page_size)
end

def parse_params(socket, %{}, :page_size), do: assign(socket, :page_size, 25)

This is of course entirely optional, and the library doesn’t monkey patch anything or name-clash with any LiveView apis, so it should be easy to try out the library and remove it if you don’t like it.

The documentation has several examples as well and the api docs are complete.

https://github.com/GrammAcc/cartograph