Maps controller filters to your resource scopes
Ruby Logos
Pull request Compare This branch is 51 commits behind plataformatec:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Gem Version Build Status Code Climate

Has scope allows you to easily create controller filters based on your resources named scopes. Imagine the following model called graduations:

class Graduation < ActiveRecord::Base
  scope :featured, -> { where(:featured => true) }
  scope :by_degree, -> degree { where(:degree => degree) }

You can use those named scopes as filters by declaring them on your controller:

class GraduationsController < ApplicationController
  has_scope :featured, :type => :boolean
  has_scope :by_degree

Now, if you want to apply them to an specific resource, you just need to call apply_scopes:

class GraduationsController < ApplicationController
  has_scope :featured, :type => :boolean
  has_scope :by_degree
  has_scope :by_period, :using => [:started_at, :ended_at]

  def index
    @graduations = apply_scopes(Graduation).all

Then for each request:

#=> acts like a normal request

#=> calls the named scope and bring featured graduations

#=> brings graduations in the given period

#=> brings featured graduations with phd degree

You can retrieve all the scopes applied in one action with current_scopes method. In the last case, it would return: { :featured => true, :by_degree => "phd" }.


Add has_scope to your Gemfile or install it from Rubygems.

gem 'has_scope'


HasScope supports several options:

  • :type - Checks the type of the parameter sent. If set to :boolean it just calls the named scope, without any argument. By default, it does not allow hashes or arrays to be given, except if type :hash or :array are set.

  • :only - In which actions the scope is applied.

  • :except - In which actions the scope is not applied.

  • :as - The key in the params hash expected to find the scope. Defaults to the scope name.

  • :using - The subkeys to be used as args when type is a hash.

  • :if - Specifies a method, proc or string to call to determine if the scope should apply.

  • :unless - Specifies a method, proc or string to call to determine if the scope should NOT apply.

  • :default - Default value for the scope. Whenever supplied the scope is always called.

  • :allow_blank - Blank values are not sent to scopes by default. Set to true to overwrite.

Block usage

has_scope also accepts a block. The controller, current scope and value are yielded to the block so the user can apply the scope on its own. This is useful in case we need to manipulate the given value:

has_scope :category do |controller, scope, value|
  value != "all" ? scope.by_category(value) : scope

When used with booleans, it just receives two arguments and is just invoked if true is given:

has_scope :not_voted_by_me, :type => :boolean do |controller, scope|

Bugs and Feedback

If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.

MIT License. Copyright 2009-2013 Plataformatec.