Cinder.UrlSync (Cinder v0.9.0)

Simple URL synchronization helper for collection components.

This module provides an easy way to enable URL state synchronization for Cinder collection components with minimal setup.

Usage

Add use Cinder.UrlSync to your LiveView
Call Cinder.UrlSync.handle_params/3 in your handle_params/3 callback
Pass url_state={@url_state} to your collection component
That's it! The helper handles all URL updates automatically.

Example

defmodule MyAppWeb.UsersLive do
  use MyAppWeb, :live_view
  use Cinder.UrlSync

  def mount(_params, _session, socket) do
    {:ok, assign(socket, :current_user, get_current_user())}
  end

  def handle_params(params, uri, socket) do
    socket = Cinder.UrlSync.handle_params(params, uri, socket)
    {:noreply, socket}
  end

  def render(assigns) do
    ~H"""
    <Cinder.collection
      resource={MyApp.User}
      actor={@current_user}
      url_state={@url_state}
    >
      <:col :let={user} field="name" filter sort>{user.name}</:col>
      <:col :let={user} field="email" filter>{user.email}</:col>
    </Cinder.collection>
    """
  end
end

The helper automatically:

Handles :table_state_change messages from collection components
Updates the URL with new collection state
Preserves other URL parameters
Works with any number of collection components on the same page

Custom URL Parameters

The URL sync helper automatically preserves custom (non-collection) query parameters while managing collection state. The collection component knows which parameters it manages (filters, page, sort, page_size, search) and will preserve any other parameters in the URL.

For example:

# URL with custom params and collection state
/users?tab=overview&view=grid&name=john&page=2

# When "name" filter is cleared, custom params are preserved
/users?tab=overview&view=grid&page=2

# When navigating to a different page, custom params remain
/users?tab=overview&view=grid&page=3

You can use any parameter names for custom state without worrying about conflicts with collection parameters. The collection automatically tracks which filter fields it manages and will only remove those when filters are cleared.

Summary

Functions

__using__(opts)

Adds URL sync support to a LiveView.

build_url(encoded_state, current_uri \\ nil, socket \\ nil)

Builds a new URL by merging collection state with existing query parameters.

extract_collection_state(params)

Extracts collection state from URL parameters using empty columns list.

extract_url_state(params)

Extracts complete URL state from URL parameters for use with collection components.

get_url_state(socket_assigns)

Helper to get the URL state for passing to collection components.

handle_params(params, uri \\ nil, socket)

Helper function to handle collection state in LiveView handle_params.

update_url(socket, encoded_state, current_uri \\ nil)

Updates the LiveView socket with new URL parameters.

Functions

using(opts)

(macro)

Adds URL sync support to a LiveView.

This macro injects the necessary handle_info/2 callback to handle collection state changes and update the URL accordingly.

build_url(encoded_state, current_uri \\ nil, socket \\ nil)

Builds a new URL by merging collection state with existing query parameters.

This function is extracted for testing purposes. It builds the URL that would be pushed by update_url/3.

Parameters

encoded_state - Map of URL parameters from collection state
current_uri - Optional current URI string to use for path resolution
socket - Optional socket for fallback path resolution

Returns

A string representing the new URL with merged query parameters

extract_collection_state(params)

Extracts collection state from URL parameters using empty columns list.

This function provides a simplified extraction that works without column metadata. It preserves page and sort information but may not fully decode filters (which is why we also preserve raw params in handle_params).

Parameters

params - URL parameters map

Returns

Map with :filters, :current_page, and :sort_by keys

extract_url_state(params)

Extracts complete URL state from URL parameters for use with collection components.

This function can be used in handle_params/3 to initialize URL state for collection components.

Example

def handle_params(params, _uri, socket) do
  url_state = Cinder.UrlSync.extract_url_state(params)
  socket = assign(socket, :url_state, url_state)
  {:noreply, socket}
end

get_url_state(socket_assigns)

Helper to get the URL state for passing to collection components.

Use this to get the URL state object created by handle_params/3.

Example

def render(assigns) do
  ~H"""
  <Cinder.collection
    resource={Album}
    actor={@current_user}
    url_state={@url_state}
    theme="minimal"
  >
    <:col :let={album} field="name" filter="text">{album.name}</:col>
    <:col :let={album} field="artist.name" filter="text">{album.artist.name}</:col>
  </Cinder.collection>
  """
end

The URL state object contains:

filters: Raw URL parameters for proper filter decoding
current_page: Current page number
sort_by: Sort configuration
uri: Current URI

handle_params(params, uri \\ nil, socket)

Helper function to handle collection state in LiveView handle_params.

This function extracts URL parameters and creates a URL state object that can be passed to collection components. It should be called from your LiveView's handle_params/3 callback.

Parameters

params - URL parameters from handle_params/3
uri - Current URI from handle_params/3 (optional but recommended)
socket - The LiveView socket

Returns

Updated socket with :url_state assign containing:

filters - Raw URL parameters for proper filter decoding
current_page - Current page number
sort_by - Sort configuration
uri - Current URI for URL generation

Example

def handle_params(params, uri, socket) do
  socket = Cinder.UrlSync.handle_params(params, uri, socket)
  {:noreply, socket}
end

def render(assigns) do
  ~H"""
  <Cinder.collection
    resource={MyApp.User}
    actor={@current_user}
    url_state={@url_state}
  >
    <:col :let={user} field="name" filter sort>{user.name}</:col>
  </Cinder.collection>
  """
end

The @url_state assign will be available for use with the collection component.

update_url(socket, encoded_state, current_uri \\ nil)

Updates the LiveView socket with new URL parameters.

This function preserves the current path and updates only the query parameters with the new collection state.

Parameters

socket - The LiveView socket
encoded_state - Map of URL parameters from collection state
current_uri - Optional current URI string to use for path resolution

Returns

Updated socket with URL changed via push_patch/2