Cinder.Table.UrlSync (Cinder v0.1.1)
View SourceSimple URL synchronization helper for Table components.
This module provides an easy way to enable URL state synchronization for Table components with minimal setup.
Usage
- Add
use Cinder.Table.UrlSync
to your LiveView - Call
Cinder.Table.UrlSync.handle_params/3
in yourhandle_params/3
callback - Pass
url_state={@url_state}
to your Table component - 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(socket, params, uri)
{: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
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.
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
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
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
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
socket
- The LiveView socketparams
- URL parameters fromhandle_params/3
uri
- Current URI fromhandle_params/3
(optional but recommended)
Returns
Updated socket with :url_state
assign containing:
filters
- Raw URL parameters for proper filter decodingcurrent_page
- Current page numbersort_by
- Sort configurationuri
- Current URI for URL generation
Example
def handle_params(params, uri, socket) do
socket = Cinder.Table.UrlSync.handle_params(socket, params, uri)
{: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.
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 socketencoded_state
- Map of URL parameters from table statecurrent_uri
- Optional current URI string to use for path resolution
Returns
Updated socket with URL changed via push_patch/2