Base behavior for Cinder filter implementations.

Defines the common interface that all filter types must implement, along with shared types and utility functions.

Quick Start

Create a custom filter by using this module:

defmodule MyApp.Filters.Slider do
  use Cinder.Filter

  @impl true
  def render(column, current_value, theme, assigns) do
    filter_options = Map.get(column, :filter_options, [])
    min_value = get_option(filter_options, :min, 0)
    max_value = get_option(filter_options, :max, 100)
    current = if current_value in [nil, ""], do: min_value, else: current_value

    assigns = %{
      column: column,
      current_value: current,
      min_value: min_value,
      max_value: max_value,
      theme: theme
    }

    ~H"""
    <div class="flex flex-col space-y-2">
      <input
        type="range"
        name={field_name(@column.field)}
        value={@current_value}
        min={@min_value}
        max={@max_value}
        phx-debounce="100"
        class={Map.get(@theme, :filter_slider_input_class, "w-full")}
      />
      <output>{@current_value}</output>
    </div>
    """
  end

  @impl true
  def process(raw_value, column) when is_binary(raw_value) do
    case Integer.parse(raw_value) do
      {value, ""} ->
        %{
          type: :slider,
          value: value,
          operator: :less_than_or_equal
        }
      _ -> nil
    end
  end

  def process(_raw_value, _column), do: nil

  @impl true
  def validate(%{type: :slider, value: value, operator: operator})
      when is_integer(value) and is_atom(operator), do: true
  def validate(_), do: false

  @impl true
  def default_options, do: [min: 0, max: 100, step: 1]

  @impl true
  def empty?(value) do
    case value do
      nil -> true
      %{value: nil} -> true
      _ -> false
    end
  end

  @impl true
  def build_query(query, field, filter_value) do
    %{value: value} = filter_value
    Cinder.Filter.Helpers.build_ash_filter(query, field, value, :less_than_or_equal)
  end
end

Then register it in your configuration:

config :cinder, :filters, slider: MyApp.Filters.Slider

This automatically:

• Adds the @behaviour Cinder.Filter declaration
• Imports Phoenix.Component for HEEx templates
• Imports helper functions from this module

Required Callbacks

All custom filters must implement these callbacks:

render/4

Renders the filter UI component.

@callback render(column :: map(), current_value :: any(), theme :: map(), assigns :: map()) :: Phoenix.LiveView.Rendered.t()

• column: Column configuration with field, label, filter_options
• current_value: The :value from process/2, or an empty value (like "") when the filter isn't in use
• theme: Theme configuration with CSS classes
• assigns: Additional assigns from the parent component

process/2

Processes raw form/URL input into structured filter data.

@callback process(raw_value :: any(), column :: map()) :: map() | nil

Must return a map with :type, :value, :operator keys, or nil.

validate/1

Validates a processed filter value.

@callback validate(value :: any()) :: boolean()

default_options/0

Returns default configuration options.

@callback default_options() :: keyword()

empty?/1

Determines if a filter value is "empty" (no filtering applied).

@callback empty?(value :: any()) :: boolean()

build_query/3

Adds the filter to the Ash query. This is what filters the records.

@callback build_query(query :: Ash.Query.t(), field :: String.t(), filter_value :: map()) :: Ash.Query.t()

Helper Functions

field_name/1

Generates proper form field names for filter inputs:

~H"""
<input name={field_name(@column.field)} ... />
"""

get_option/3

Safely extracts options from filter configuration with defaults:

filter_options = Map.get(column, :filter_options, [])
placeholder = get_option(filter_options, :placeholder, "Enter text...")

Query Building Patterns

Recommended Approach: Use the Centralized Helper

def build_query(query, field, filter_value) do
  %{value: value, operator: operator} = filter_value

  # Use the centralized helper which supports direct, relationship, and embedded fields
  Cinder.Filter.Helpers.build_ash_filter(query, field, value, operator)
end

Field Filtering

Cinder.Filter.Helpers.build_ash_filter/4 builds the filter for any field notation: direct fields, relationships ("user.name") and embedded fields (below), with :equals, :contains, :starts_with, :ends_with, :in, and the comparisons (:greater_than, :less_than_or_equal and so on):

def build_query(query, field, filter_value) do
  %{value: value} = filter_value
  Cinder.Filter.Helpers.build_ash_filter(query, field, value, :equals)
end

Prefer it to building ref/1 expressions from field yourself: it handles every notation, and never turns a name into a new atom (String.to_atom/1 on names isn't safe in general, since atoms are never garbage collected).

Embedded Field Filtering

Embedded fields use double-underscore notation, e.g. "profile__first_name". This is the same notation you write in column definitions, so build_query/3 receives field exactly as the column declared it:

def build_query(query, field, filter_value) do
  %{value: value} = filter_value

  # The centralized helper automatically detects and handles embedded fields
  Cinder.Filter.Helpers.build_ash_filter(query, field, value, :equals)
end

Supported embedded field notations:

• Basic embedded: profile__first_name
• Nested embedded: settings__address__street
• Mixed relationship + embedded: user.profile__first_name
• Complex mixed: company.settings__address__city

Best Practices

1. Always implement build_query/3 - This is what actually filters data
2. Handle edge cases in process/2 - Return nil for invalid input
3. Validate filter values - Check structure and data types
4. Document your filters - Include usage examples and options