Cinder.Collection (Cinder v0.12.1)

Unified collection component for displaying data in table, list, or grid layouts.

This component provides a single API for all collection displays, with the layout attribute selecting how items are rendered. All layouts share the same filtering, sorting, pagination, and URL sync capabilities.

Layouts

:table (default) - Traditional HTML table with sortable headers
:list - Vertical list with sort button group
:grid - Responsive card grid with sort button group

Basic Usage

Table Layout (default)

<Cinder.collection 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>
</Cinder.collection>

List Layout

<Cinder.collection resource={MyApp.User} actor={@current_user} layout={:list}>
  <:col field="name" filter sort />
  <:col field="status" filter={:select} />

  <:item :let={user}>
    <div class="flex justify-between">
      <span class="font-bold">{user.name}</span>
      <span>{user.status}</span>
    </div>
  </:item>
</Cinder.collection>

Grid Layout

<Cinder.collection resource={MyApp.Product} actor={@current_user} layout={:grid}>
  <:col field="name" filter sort search />
  <:col field="category" filter={:select} />

  <:item :let={product}>
    <h3 class="font-bold">{product.name}</h3>
    <p class="text-gray-600">{product.category}</p>
    <p class="text-lg font-semibold">${product.price}</p>
  </:item>
</Cinder.collection>

Grid Columns

Control the number of grid columns with the grid_columns attribute:

<!-- Fixed 4 columns -->
<Cinder.collection resource={MyApp.Product} layout={:grid} grid_columns={4}>
  ...
</Cinder.collection>

<!-- Responsive columns -->
<Cinder.collection resource={MyApp.Product} layout={:grid} grid_columns={[xs: 1, md: 2, lg: 3, xl: 4]}>
  ...
</Cinder.collection>

Layout-Specific Attributes

Attribute	Table	List	Grid	Description
`<:col>` content	✅ Rendered	❌ Ignored	❌ Ignored	Cell content for table rows
`<:item>` slot	❌ Ignored	✅ Required	✅ Required	Template for each item
`sort_label`	❌ N/A	✅ Button label	✅ Button label	Label for sort button group
`container_class`	❌ N/A	✅ Override	✅ Override	Custom container CSS
`grid_columns`	❌ N/A	❌ N/A	✅ Column count	Number of grid columns
`click`	✅ Row click	✅ Item click	✅ Item click	Click handler

Custom Controls Layout

Use the :controls slot to customize how filters and search are rendered while keeping Cinder's state management, URL sync, and query building intact:

<Cinder.collection resource={MyApp.User} actor={@current_user}>
  <:col :let={user} field="name" filter sort search>{user.name}</:col>
  <:col :let={user} field="status" filter={:select}>{user.status}</:col>

  <:controls :let={controls}>
    <Cinder.Controls.render_header {controls} />
    <div class="grid grid-cols-2 gap-4">
      <Cinder.Controls.render_filter
        :for={filter <- controls.filters}
        filter={filter}
      />
    </div>
  </:controls>
</Cinder.collection>

See Cinder.Controls for the full API and more examples.

Summary

Functions

build_query_columns(processed_columns, processed_filter_slots)

Builds the list of columns used for query operations (filtering AND searching).

collection(assigns)

process_columns(col_slots, resource)

Process column definitions into the format expected by the underlying component.

process_filter_slots(filter_slots, resource)

Process filter-only slot definitions into the format expected by the filter system.

process_search_config(search_config, columns)

Process unified search configuration into individual components. Returns {label, placeholder, enabled, search_fn}.

Functions

build_query_columns(processed_columns, processed_filter_slots)

Builds the list of columns used for query operations (filtering AND searching).

This function combines:

Filterable columns: needed for filter application
Searchable columns: needed for search even if not filterable
Filter-only slots: dedicated filter controls not tied to display columns

NOTE: Sortable-only columns are NOT included here - sorting uses display_columns because sort controls are tied to column headers.

Raises ArgumentError if the same field is defined in both a filterable column and a filter-only slot.