Module: Datagrid::Filters

Extended by:
ActiveSupport::Concern
Included in:
Base
Defined in:
lib/datagrid/filters.rb,
lib/datagrid/filters/base_filter.rb,
lib/datagrid/filters/date_filter.rb,
lib/datagrid/filters/enum_filter.rb,
lib/datagrid/filters/float_filter.rb,
lib/datagrid/filters/ranged_filter.rb,
lib/datagrid/filters/string_filter.rb,
lib/datagrid/filters/boolean_filter.rb,
lib/datagrid/filters/default_filter.rb,
lib/datagrid/filters/dynamic_filter.rb,
lib/datagrid/filters/integer_filter.rb,
lib/datagrid/filters/select_options.rb,
lib/datagrid/filters/date_time_filter.rb,
lib/datagrid/filters/extended_boolean_filter.rb

Overview

Defines the accessible attribute that is used to filter the scope by the specified value with specified code.

class UserGrid < ApplicationGrid
  scope do
    User
  end

  filter(:name)
  filter(:posts_count, :integer) do |value|
    self.where(["posts_count >= ?", value])
  end
end

Each filter becomes a grid attribute.

To create a grid displaying all users with the name 'John' who have more than zero posts:

grid = UserGrid.new(posts_count: 1, name: "John")
grid.assets # SELECT * FROM users WHERE users.posts_count > 1 AND name = 'John'

Filter blocks should always return a chainable ORM object (e.g., ActiveRecord::Relation) rather than an Array.

Filter Block

Filter blocks should have at least one argument representing the value assigned to the grid object attribute:

filter(:name, :string) # { |value| where(name: value) }

You can pass additional arguments:

filter(:name, :string) { |value, scope| scope.where("name ilike ?", "%#{value}%") }
filter(:name, :string) do |value, scope, grid|
  scope.where("name #{grid.predicate} ?", "%#{value}%")
end

Filter Types

Filters perform automatic type conversion. Supported filter types include:

  • default
  • date
  • datetime
  • enum
  • boolean
  • xboolean
  • integer
  • float
  • string
  • dynamic

Default

:default - Leaves the value as is.

Date

:date - Converts value to a date. Supports the :range option to accept date ranges.

filter(:created_at, :date, range: true, default: proc { 1.month.ago.to_date..Date.today })

Datetime

:datetime - Converts value to a timestamp. Supports the :range option to accept time ranges.

filter(:created_at, :datetime, range: true, default: proc { 1.hour.ago..Time.now })

Enum

:enum - For collection selection with options like :select and :multiple.

filter(:user_type, :enum, select: ['Admin', 'Customer', 'Manager'])
filter(:category_id, :enum, select: proc { Category.all.map { |c| [c.name, c.id] } }, multiple: true)

Boolean

:boolean - Converts value to true or false.

Xboolean

:xboolean - Subtype of enum filter that provides "Yes", "No", and "Any" options.

filter(:active, :xboolean)

Integer

:integer - Converts value to an integer. Supports the :range option.

filter(:posts_count, :integer, range: true, default: (1..nil))

String

:string - Converts value to a string.

filter(:email, :string)

Dynamic

Provides a builder for dynamic SQL conditions.

filter(:condition1, :dynamic)
filter(:condition2, :dynamic)
UsersGrid.new(condition1: [:name, "=~", "John"], condition2: [:posts_count, ">=", 1])
UsersGrid.assets # SELECT * FROM users WHERE name like '%John%' and posts_count >= 1

Filter Options

Options that can be passed to any filter:

  • :header - Human-readable filter name (default: generated from the filter name).
  • :default - Default filter value (default: nil).
  • :multiple - Allows multiple values (default: false).
  • :allow_nil - Whether to apply the filter when the value is nil (default: false).
  • :allow_blank - Whether to apply the filter when the value is blank (default: false).

Example:

filter(:id, :integer, header: "Identifier")
filter(:created_at, :date, range: true, default: proc { 1.month.ago.to_date..Date.today })

Default Filter Options

Default options for all filters in a grid can be set using default_filter_options.

self.default_filter_options = { header: "" }

It can also accept a proc with the filter instance as an argument:

self.default_filter_options = ->(filter) { { header: I18n.t(filter.name, scope: 'filters') } }

Localization

Filter labels can be localized or specified via the :header option:

filter(:created_at, :date, header: "Creation date")
filter(:created_at, :date, header: proc { I18n.t("creation_date") })

Defined Under Namespace

Modules: ClassMethods, RangedFilter, SelectOptions Classes: BaseFilter, BooleanFilter, DateFilter, DateTimeFilter, DefaultFilter, DynamicFilter, EnumFilter, ExtendedBooleanFilter, FloatFilter, IntegerFilter, StringFilter

Instance Method Summary collapse

Instance Method Details

#default_filter_options ⇒ Hash, Proc

Returns default options passed to #filter method call, or a proc that returns them.

Returns:

  • (Hash, Proc) —

    default options passed to #filter method call, or a proc that returns them.

See Also:



155
 
# File 'lib/datagrid/filters.rb', line 155

require "datagrid/filters/base_filter"

#default_filter_options=(value) ⇒ Hash, Proc

Returns default options passed to #filter method call, or a proc that returns them.

Examples:

Set the default header for all filters

self.default_filter_options = ->(filter) { { header: I18n.t(filter.name, scope: 'my_scope.filters') } }

Parameters:

  • value (Hash, Proc) —

    default options passed to #filter method call. When a proc is passed, it will be called with the filter instance as an argument, and expected to produce the options hash.

Returns:

  • (Hash, Proc) —

    default options passed to #filter method call, or a proc that returns them.




# File 'lib/datagrid/filters.rb', line 143

#filter_by(*filters) ⇒ Array<Object>

Returns assets filtered only by specified filters.

Returns:

  • (Array<Object>) —

    assets filtered only by specified filters



324
325
326
 
# File 'lib/datagrid/filters.rb', line 324

def filter_by(*filters)
  apply_filters(scope, filters.map { |f| filter_by_name(f) })
end

#filter_by_name(name) ⇒ Datagrid::Filters::BaseFilter?

Returns filter object with the given name.

Returns:



319
320
321
 
# File 'lib/datagrid/filters.rb', line 319

def filter_by_name(name)
  self.class.filter_by_name(name)
end

#filter_value(filter) ⇒ Object

Returns filter value for given filter definition.

Returns:

  • (Object) —

    filter value for given filter definition



303
304
305
 
# File 'lib/datagrid/filters.rb', line 303

def filter_value(filter)
  self[filter.name]
end

#filter_value_as_string(name) ⇒ String

Returns string representation of filter value.

Returns:

  • (String) —

    string representation of filter value



308
309
310
311
312
313
314
315
316
 
# File 'lib/datagrid/filters.rb', line 308

def filter_value_as_string(name)
  filter = filter_by_name(name)
  value = filter_value(filter)
  if value.is_a?(Array)
    value.map { |v| filter.format(v) }.join(filter.separator)
  else
    filter.format(value)
  end
end

#filters ⇒ Array<Datagrid::Filters::BaseFilter>

Returns all currently enabled filters.

Returns:



346
347
348
349
350
 
# File 'lib/datagrid/filters.rb', line 346

def filters
  self.class.filters.select do |filter|
    filter.enabled?(self)
  end
end

#select_all(filter) ⇒ void

This method returns an undefined value.

Returns sets all options as selected for a filter that has options.



335
336
337
338
 
# File 'lib/datagrid/filters.rb', line 335

def select_all(filter)
  filter = find_select_filter(filter)
  self[filter.name] = select_values(filter)
end

#select_options(filter) ⇒ Array

Returns the select options for the filter.

Returns:

  • (Array) —

    the select options for the filter

Raises:

  • (ArgumentError) —

    if the filter doesn't support select options



330
331
332
 
# File 'lib/datagrid/filters.rb', line 330

def select_options(filter)
  find_select_filter(filter).select(self)
end

#select_values(filter) ⇒ Array

Returns all possible values for the filter.

Returns:

  • (Array) —

    all possible values for the filter



341
342
343
 
# File 'lib/datagrid/filters.rb', line 341

def select_values(filter)
  find_select_filter(filter).select_values(self)
end