Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 112 lines (75 sloc) 3.279 kB
bdd1069 @beerlington Converting readme to markdown
beerlington authored
1 ## HasScope
2
3 Has scope allows you to easily create controller filters based on your resources named scopes.
4 Imagine the following model called graduations:
5
6 ```ruby
7 class Graduation < ActiveRecord::Base
4640c7c @lucasmazza Update dependencies and documentation, also remove `init.rb` files.
lucasmazza authored
8 scope :featured, where(:featured => true)
9 scope :by_degree, proc { |degree| where(:degree => degree) }
bdd1069 @beerlington Converting readme to markdown
beerlington authored
10 end
11 ```
12
13 You can use those named scopes as filters by declaring them on your controller:
14
15 ```ruby
16 class GraduationsController < ApplicationController
17 has_scope :featured, :type => :boolean
18 has_scope :by_degree
19 end
20 ```
21
22 Now, if you want to apply them to an specific resource, you just need to call `apply_scopes`:
23
24 ```ruby
25 class GraduationsController < ApplicationController
26 has_scope :featured, :type => :boolean
27 has_scope :by_degree
28 has_scope :by_period, :using => [:started_at, :ended_at]
29
30 def index
31 @graduations = apply_scopes(Graduation).all
32 end
33 end
34 ```
35
36 Then for each request:
37
38 ```
39 /graduations
40 #=> acts like a normal request
41
42 /graduations?featured=true
43 #=> calls the named scope and bring featured graduations
44
45 /graduations?params[by_period][started_at]=20100701&params[by_period][ended_at]=20101013
46 #=> brings graduations in the given period
47
48 /graduations?featured=true&by_degree=phd
49 #=> brings featured graduations with phd degree
50 ```
51
52 You can retrieve all the scopes applied in one action with `current_scopes` method.
53 In the last case, it would return: { :featured => true, :by_degree => "phd" }.
54
55 ## Installation
56
4640c7c @lucasmazza Update dependencies and documentation, also remove `init.rb` files.
lucasmazza authored
57 Add `has_scope` to your Gemfile or install it from Rubygems.
bdd1069 @beerlington Converting readme to markdown
beerlington authored
58
4640c7c @lucasmazza Update dependencies and documentation, also remove `init.rb` files.
lucasmazza authored
59 ```ruby
60 gem 'has_scope'
bdd1069 @beerlington Converting readme to markdown
beerlington authored
61 ```
62
63 ## Options
64
65 HasScope supports several options:
66
67 * `: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.
68
69 * `:only` - In which actions the scope is applied.
70
71 * `:except` - In which actions the scope is not applied.
72
73 * `:as` - The key in the params hash expected to find the scope. Defaults to the scope name.
74
75 * `:using` - The subkeys to be used as args when type is a hash.
76
77 * `:if` - Specifies a method, proc or string to call to determine if the scope should apply.
78
79 * `:unless` - Specifies a method, proc or string to call to determine if the scope should NOT apply.
80
81 * `:default` - Default value for the scope. Whenever supplied the scope is always called.
82
83 * `:allow_blank` - Blank values are not sent to scopes by default. Set to true to overwrite.
84
85 ## Block usage
86
87 has_scope also accepts a block. The controller, current scope and value are yielded
88 to the block so the user can apply the scope on its own. This is useful in case we
89 need to manipulate the given value:
90
91 ```ruby
92 has_scope :category do |controller, scope, value|
93 value != "all" ? scope.by_category(value) : scope
94 end
95 ```
96
97 When used with booleans, it just receives two arguments and is just invoked if true is given:
98
99 ```ruby
100 has_scope :not_voted_by_me, :type => :boolean do |controller, scope|
4640c7c @lucasmazza Update dependencies and documentation, also remove `init.rb` files.
lucasmazza authored
101 scope.not_voted_by(controller.current_user.id)
bdd1069 @beerlington Converting readme to markdown
beerlington authored
102 end
103 ```
104
105 ## Bugs and Feedback
106
107 If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.
108
109 http://github.com/plataformatec/has_scope/issues
110
d7fd3e9 @lucasmazza Update master
lucasmazza authored
111 MIT License. Copyright 2009-2012 Plataformatec. http://blog.plataformatec.com.br
Something went wrong with that request. Please try again.