Cinder.Table.UrlSync (Cinder v0.5.0)

View Source

Simple URL synchronization helper for Table components.

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

Usage

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

Example

defmodule MyAppWeb.UsersLive do
  use MyAppWeb, :live_view
  use Cinder.Table.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.Table.UrlSync.handle_params(params, uri, socket)
    {:noreply, socket}
  end

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

  # Or with a pre-configured query:
  def render_with_query(assigns) do
    ~H"""
    <Cinder.Table.table
      query={MyApp.User |> Ash.Query.filter(active: true)}
      actor={@current_user}
      url_state={@url_state}
    >
      <:col field="name" filter sort>Name</:col>
      <:col field="email" filter>Email</:col>
    </Cinder.Table.table>
    """
  end
end

The helper automatically:

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

Summary

Functions

Adds URL sync support to a LiveView.

Extracts table state from URL parameters using empty columns list.

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

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

Helper function to handle table state in LiveView handle_params.

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 table state changes and update the URL accordingly.

extract_table_state(params)

Extracts table 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 table components.

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

Example

def handle_params(params, _uri, socket) do
  url_state = Cinder.Table.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 table components.

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

Example

def render(assigns) do
  ~H"""
  <Cinder.Table.table
    resource={Album}
    actor={@current_user}
    url_state={@url_state}
    theme="minimal"
  >
    <:col field="name" filter="text">Name</:col>
    <:col field="artist.name" filter="text">Artist</:col>
  </Cinder.Table.table>
  """
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 table state in LiveView handle_params.

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

Parameters

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.Table.UrlSync.handle_params(params, uri, socket)
  {:noreply, socket}
end

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

The @url_state assign will be available for use with the Table 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 table state.

Parameters

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

Returns

Updated socket with URL changed via push_patch/2