Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Maps controller filters to your resource scopes

tag: v0.4.1

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.rdoc

HasScope

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
  named_scope :featured, :conditions => { :featured => true }
  named_scope :by_degree, proc {|degree| { :conditions => { :degree => degree } } }
end

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
end

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

  def index
    @graduations = apply_scopes(Graduation).all
  end
end

Then for each request:

/graduations
#=> acts like a normal request

/graduations?featured=true
#=> calls the named scope and bring featured graduations

/graduations?featured=true&by_degree=phd
#=> 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” }.

Installation

HasScope is available as gem on Gemcutter, so just run the following:

sudo gem install has_scope

If you want it as plugin, just do:

script/plugin install git://github.com/plataformatec/has_scope.git

Options

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.

  • :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
end

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|
  scope.not_voted_by(controller.current_user.id) 
end

Bugs and Feedback

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

github.com/plataformatec/has_scope/issues

MIT License. Copyright 2009 Plataforma Tecnologia. blog.plataformatec.com.br

Something went wrong with that request. Please try again.