Filters
filter adds a filter to the filter bar of an index page or a dashboard.
Quick exampleβ
cm_index do
filter %i[name email], :search, placeholder: "Search"
filter :status, :multi_select, collection: ["draft", "published"]
filter :user_id, :single_select, helper_method: :select_options_for_user
filter :created_at, :date
filter :age, :range
filter :email, :string
end
Optionsβ
filter(db_column_name, filter_type = nil, options = {})
| Filter type | Matches |
|---|---|
:search | Text search across one or more columns. The only type that accepts an array of columns. |
:single_select | One option. Defaults to the model's enum values when the column is an enum. |
:multi_select | Any of the selected options. Used automatically when filter_type is omitted on an enum column. |
:date | A date range. |
:range | A numeric range. |
:string | A text value with operators (contains, is, β¦). |
| Name | Type | Default | Description |
|---|---|---|---|
placeholder | String | depends on type | Placeholder text. |
display_name | String | Column name, titleized | Label of the filter. |
collection | Array | nil | Options for select filters: [[label, value], ...] or [value, ...]. |
helper_method | Symbol | nil | Method in CmAdmin::CustomHelper, called with no arguments, returning the select options. |
filter_with | Symbol | nil | Model scope that applies the filter. See Custom filter method. |
active_by_default | Boolean | nil | Show the filter in the bar without the user adding it. |
default_value | Proc | nil | Lambda returning the value applied when the URL has no filter params. |
allow_select_all_option | Boolean | true | Show a (Select All) option in :multi_select filters. UI only: the selected values are sent. |
allow_empty_option | Boolean | true (false with filter_with) | Show an (Empty) option in select filters. |
display_if | Proc | ->(_arg) { true } | Lambda returning whether to show the filter. |
Recipesβ
Default filter valuesβ
filter :status, :single_select, collection: ["draft", "published"], default_value: -> { "draft" }
filter :category, :multi_select, collection: ["A", "B", "C"], default_value: -> { ["A", "B"] }
filter :created_at, :date, default_value: -> { "#{30.days.ago.to_date} to #{Date.today}" }
filter :user_id, :single_select, helper_method: :user_collection, default_value: -> { Current.user.id }
Options from a helperβ
filter :user_id, :single_select, helper_method: :select_options_for_user
app/helpers/cm_admin/custom_helper.rb
def select_options_for_user
User.order(:first_name).map { |user| [user.full_name, user.id] }
end
Show filters without the user adding themβ
active_by_default pins the filter into the bar on first load:
filter :status, :multi_select, active_by_default: true
filter :user_id, :multi_select, helper_method: :select_options_for_user,
display_name: "Leave Applicant", active_by_default: true
Ranges and datesβ
filter :salary, :range # numeric min/max inputs
filter :start_date, :date # date range picker
filter :reason, :string, placeholder: "Search reason"
Custom filter logicβ
filter :status, :single_select, collection: %w[open closed], filter_with: :by_ticket_status
filter :currently_on_leave, :single_select, collection: [["Yes", true], ["No", false]],
filter_with: :currently_on_leave
See Custom filter method for the scope signature.
Relatedβ
- Advanced filters: nested AND/OR conditions with operators
- Saved views: save filters per user
- Global search