Skip to main content

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 typeMatches
:searchText search across one or more columns. The only type that accepts an array of columns.
:single_selectOne option. Defaults to the model's enum values when the column is an enum.
:multi_selectAny of the selected options. Used automatically when filter_type is omitted on an enum column.
:dateA date range.
:rangeA numeric range.
:stringA text value with operators (contains, is, …).
NameTypeDefaultDescription
placeholderStringdepends on typePlaceholder text.
display_nameStringColumn name, titleizedLabel of the filter.
collectionArraynilOptions for select filters: [[label, value], ...] or [value, ...].
helper_methodSymbolnilMethod in CmAdmin::CustomHelper, called with no arguments, returning the select options.
filter_withSymbolnilModel scope that applies the filter. See Custom filter method.
active_by_defaultBooleannilShow the filter in the bar without the user adding it.
default_valueProcnilLambda returning the value applied when the URL has no filter params.
allow_select_all_optionBooleantrueShow a (Select All) option in :multi_select filters. UI only: the selected values are sent.
allow_empty_optionBooleantrue (false with filter_with)Show an (Empty) option in select filters.
display_ifProc->(_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.