Cinder (Cinder v0.3.0)
View SourceCinder is a powerful, intelligent data table component for Phoenix LiveView applications with seamless Ash Framework integration.
Quick Start
The simplest table requires only a resource (or query) and actor:
# Using resource parameter
<Cinder.Table.table resource={MyApp.User} actor={@current_user}>
<:col :let={user} field="name" filter sort>{user.name}</:col>
<:col :let={user} field="email" filter>{user.email}</:col>
<:col :let={user} field="created_at" sort>{user.created_at}</:col>
</Cinder.Table.table>
# Using query parameter
<Cinder.Table.table query={MyApp.User} actor={@current_user}>
<:col :let={user} field="name" filter sort>{user.name}</:col>
<:col :let={user} field="email" filter>{user.email}</:col>
<:col :let={user} field="created_at" sort>{user.created_at}</:col>
</Cinder.Table.table>
# Advanced query usage
<Cinder.Table.table query={MyApp.User |> Ash.Query.filter(active: true)} actor={@current_user}>
<:col :let={user} field="name" filter sort>{user.name}</:col>
<:col :let={user} field="email" filter>{user.email}</:col>
<:col :let={user} field="created_at" sort>{user.created_at}</:col>
</Cinder.Table.table>
Custom Filters
Cinder supports custom filter types through a simple configuration-based approach:
# 1. Configure your filters in config.exs
config :cinder, :filters, [
slider: MyApp.Filters.Slider,
color_picker: MyApp.Filters.ColorPicker
]
# 2. Set up Cinder in your application.ex
def start(_type, _args) do
Cinder.setup() # Automatically registers all configured filters
# ... rest of application startup
end
# 3. Create custom filters with minimal boilerplate
defmodule MyApp.Filters.Slider do
use Cinder.Filter # Includes everything you need
@impl true
def render(column, current_value, theme, assigns) do
# Your filter implementation with HEEx templates
end
@impl true
def process(raw_value, column) do
# Transform form input to filter value
end
@impl true
def validate(filter_value), do: # Validate filter value
@impl true
def default_options, do: [min: 0, max: 100, step: 1]
@impl true
def empty?(value), do: # Check if filter is empty
end
# 4. Use in your tables
<:col field="price" filter={:slider} filter_options={[min: 0, max: 1000]}>
${product.price}
</:col>
That's it! No manual registration, no complex setup - just configure and use.
Key Features
- Intelligent Defaults: Automatic filter type detection from Ash resource attributes
- Minimal Configuration: 70% fewer attributes required compared to traditional table components
- URL State Management: Filters, pagination, and sorting synchronized with browser URL
- Relationship Support: Dot notation for related fields (e.g.,
user.department.name
) - Custom Filters: Pluggable filter system with configuration-based registration
- Flexible Theming: Built-in presets and full customization
- Ash Integration: Native support for Ash Framework resources and authorization
Main Components
Cinder.Table
- The main table componentCinder.Table.UrlSync
- URL state management helperCinder.Filter
- Base behavior for custom filtersCinder.setup/0
- One-time setup for custom filters
For comprehensive examples and documentation, see the README and Examples.
Summary
Functions
Sets up Cinder with configured custom filters.
This is the recommended way to use custom filters in Cinder. Call this function once during application startup to automatically register all custom filters defined in your configuration.
Configuration
Define your custom filters in your application configuration:
config :cinder, :filters, [
slider: MyApp.Filters.Slider,
color_picker: MyApp.Filters.ColorPicker
]
Usage
Call setup/0
once in your application startup:
# In your application.ex
def start(_type, _args) do
Cinder.setup() # Registers all configured filters automatically
children = [
# ... your application's children
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
What it does
- Registers all custom filters from configuration
- Validates that all filter modules implement the required behavior
- Provides helpful logging for successful registrations and errors
- Gracefully handles configuration issues without breaking startup
Returns
Always returns :ok
. Any registration issues are logged as warnings
but don't prevent application startup.
Examples
# Successful setup with filters
Cinder.setup()
# => :ok
# Logs: "Cinder: Registered 3 custom filters: slider, color_picker, date_picker"
# Setup with configuration errors
Cinder.setup()
# => :ok
# Logs: "Cinder: Some custom filters failed to register: ..."