has_scope

When type: :boolean is set, the scope is called without arguments if the parameter is a "true" value.

• True values: 'true' and '1' are parsed as true.
• False values: Everything else is parsed as false.
• Important: A bare parameter (e.g., ?active) results in nil, which is treated as false. To pass true as an argument to a scope, use ?active=true or ?active=1.

If allow_blank: true is set, the scope will be called with the actual value (including blank values) instead of just being triggered by truthiness.

Add has_scope to your Gemfile to use it in your Ruby or Rails project.

Using Bundler:

bundle add has_scope

Or manually in your Gemfile:

gem 'has_scope'

To use HasScope outside of a Rails controller (e.g., in a Query Object), include the HasScope module. When calling apply_scopes, you must pass the collection as the first argument and the parameters hash as the second argument.

Example implementation:

class GraduationsSearchQuery
  include HasScope

  has_scope :featured, type: :boolean
  has_scope :by_degree
  has_scope :by_period, using: %i[started_at ended_at], type: :hash

  def perform(collection: Graduation, params: {})
    apply_scopes(collection, params)
  end
end

# Usage in a controller:
# @graduations = GraduationsSearchQuery.new.perform(collection: Graduation, params: params)

In Rails, has_scope is automatically available in all controllers. Use it to declare which model scopes are permitted to be applied based on incoming request parameters. To actually apply these scopes to a resource, call apply_scopes(ResourceClass).

Example declaration and usage:

class GraduationsController < ApplicationController
  # Declare permitted scopes
  has_scope :featured, type: :boolean
  has_scope :by_degree
  has_scope :by_period, using: %i[started_at ended_at], type: :hash

  def index
    # Apply the declared scopes to the Graduation model
    @graduations = apply_scopes(Graduation).all
  end
end

The current_scopes method returns a hash of all scopes that were successfully applied during the current request. The keys are the scope names and the values are the values used to call them.

• In Controllers/Views: It is available as a helper method.
• In POROs: It is a protected method. To access it externally, you must explicitly make it public using public :current_scopes.

Example output: If ?featured=true&by_degree=phd is passed, current_scopes returns:

{ featured: true, by_degree: 'phd' }

# Inside a controller or view
current_scopes
#=> { featured: true, by_degree: 'phd' }

If you receive a hash of parameters but your scope expects multiple individual arguments, use the :using option. This requires :type to be set to :hash.

Example: If your URL is ?filter[start_date]=2023-01-01&filter[end_date]=2023-12-31 and your scope is by_period(start, end):

# The :using option tells HasScope to extract :start_date and :end_date
# from the :filter hash and pass them as arguments.
has_scope :filter, type: :hash, as: :filter, using: [:start_date, :end_date]

The :in option is a convenience shortcut. When you use :in, it automatically sets :as to the value of :in and sets :using to the list of scope names provided.

# This is equivalent to:
# has_scope :filter, type: :hash, as: :filter, using: [:start_date, :end_date]
has_scope :filter, in: :filter, using: [:start_date, :end_date]

When apply_scopes is called, it populates a current_scopes hash containing the keys and values that were actually used to trigger the scopes. This is useful for tracking which filters are currently active in your UI.

In Rails, current_scopes is registered as a helper_method, making it available in your views.

The apply_scopes method is used within a controller action to execute the scopes defined via has_scope on a target object (usually a model class).

It inspects the params hash (or a provided hash), validates the values against the configured :type, and applies the resulting scopes to the target object. It returns the modified target.

# Inside a controller action
def index
  # Graduation is the target class
  # apply_scopes will return Graduation modified by any matching params
  @graduations = apply_scopes(Graduation).all
end