Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 207 lines (193 sloc) 6.789 kb
0cfb8c7 @ryanb adding basic ability module
authored
1 module CanCan
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
2
3 # This module is designed to be included into an Ability class. This will
4 # provide the "can" methods for defining and checking abilities.
5 #
6 # class Ability
7 # include CanCan::Ability
8 #
9 # def initialize(user)
10 # if user.admin?
11 # can :manage, :all
12 # else
13 # can :read, :all
14 # end
15 # end
16 # end
17 #
0cfb8c7 @ryanb adding basic ability module
authored
18 module Ability
c663eff @ryanb using instance_exec to change scope of can blocks to instance of ability...
authored
19 attr_accessor :user
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
20
21 # Use to check the user's permission for a given action and object.
22 #
23 # can? :destroy, @project
24 #
25 # You can also pass the class instead of an instance (if you don't have one handy).
26 #
27 # can? :create, Project
28 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
29 # Not only can you use the can? method in the controller and view (see ControllerAdditions),
30 # but you can also call it directly on an ability instance.
31 #
32 # ability.can? :destroy, @project
33 #
34 # This makes testing a user's abilities very easy.
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
35 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
36 # def test "user can only destroy projects which he owns"
37 # user = User.new
38 # ability = Ability.new(user)
39 # assert ability.can?(:destroy, Project.new(:user => user))
40 # assert ability.cannot?(:destroy, Project.new)
41 # end
42 #
c40490d @ryanb refactoring ability can? method - closes #12
authored
43 def can?(action, noun) # TODO this could use some refactoring
44 (@can_definitions || []).reverse.each do |base_behavior, defined_action, defined_noun, defined_block|
45 defined_actions = expand_actions(defined_action)
46 defined_nouns = [defined_noun].flatten
47 if includes_action?(defined_actions, action) && includes_noun?(defined_nouns, noun)
48 result = can_perform_action?(action, noun, defined_actions, defined_nouns, defined_block)
49 return base_behavior ? result : !result
0cfb8c7 @ryanb adding basic ability module
authored
50 end
51 end
52 false
53 end
54
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
55 # Convenience method which works the same as "can?" but returns the opposite value.
56 #
57 # cannot? :destroy, @project
58 #
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - closes...
authored
59 def cannot?(*args)
60 !can?(*args)
61 end
62
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
63 # Defines which abilities are allowed using two arguments. The first one is the action
64 # you're setting the permission for, the second one is the class of object you're setting it on.
65 #
66 # can :update, Article
67 #
68 # You can pass an array for either of these parameters to match any one.
69 #
70 # can [:update, :destroy], [Article, Comment]
71 #
72 # In this case the user has the ability to update or destroy both articles and comments.
73 #
74 # You can pass a block to provide logic based on the article's attributes.
75 #
76 # can :update, Article do |article|
77 # article && article.user == user
78 # end
79 #
80 # If the block returns true then the user has that :update ability for that article, otherwise he
81 # will be denied access. It's possible for the passed in model to be nil if one isn't specified,
82 # so be sure to take that into consideration.
83 #
84 # You can pass :all to reference every type of object. In this case the object type will be passed
85 # into the block as well (just in case object is nil).
86 #
87 # can :read, :all do |object_class, object|
88 # object_class != Order
89 # end
90 #
91 # Here the user has permission to read all objects except orders.
92 #
93 # You can also pass :manage as the action which will match any action. In this case the action is
94 # passed to the block.
95 #
96 # can :manage, Comment do |action, comment|
97 # action != :destroy
98 # end
99 #
e603655 @ryanb support custom objects (usually symbols) in can definition - closes #8
authored
100 # You can pass custom objects into this "can" method, this is usually done through a symbol
101 # and is useful if a class isn't available to define permissions on.
102 #
103 # can :read, :stats
104 # can? :read, :stats # => true
105 #
c40490d @ryanb refactoring ability can? method - closes #12
authored
106 def can(action, noun, &block)
107 @can_definitions ||= []
108 @can_definitions << [true, action, noun, block]
d4405e6 @ryanb adding cannot method to define which abilities cannot be done - closes #...
authored
109 end
110
111 # Define an ability which cannot be done. Accepts the same arguments as "can".
112 #
113 # can :read, :all
114 # cannot :read, Comment
115 #
116 # A block can be passed just like "can", however if the logic is complex it is recommended
117 # to use the "can" method.
118 #
119 # cannot :read, Product do |product|
120 # product.invisible?
121 # end
122 #
c40490d @ryanb refactoring ability can? method - closes #12
authored
123 def cannot(action, noun, &block)
124 @can_definitions ||= []
125 @can_definitions << [false, action, noun, block]
4b6f538 @ryanb moving can definition into ability instance instead of class, this remov...
authored
126 end
127
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
128 # Alias one or more actions into another one.
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
129 #
130 # alias_action :update, :destroy, :to => :modify
131 # can :modify, Comment
132 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
133 # Then :modify permission will apply to both :update and :destroy requests.
134 #
135 # can? :update, Comment # => true
136 # can? :destroy, Comment # => true
137 #
138 # This only works in one direction. Passing the aliased action into the "can?" call
139 # will not work because aliases are meant to generate more generic actions.
140 #
141 # alias_action :update, :destroy, :to => :modify
142 # can :update, Comment
143 # can? :modify, Comment # => false
144 #
145 # Unless that exact alias is used.
146 #
147 # can :modify, Comment
148 # can? :modify, Comment # => true
149 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
150 # The following aliases are added by default for conveniently mapping common controller actions.
151 #
152 # alias_action :index, :show, :to => :read
153 # alias_action :new, :to => :create
154 # alias_action :edit, :to => :update
155 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
156 # This way one can use params[:action] in the controller to determine the permission.
4b6f538 @ryanb moving can definition into ability instance instead of class, this remov...
authored
157 def alias_action(*args)
158 target = args.pop[:to]
c40490d @ryanb refactoring ability can? method - closes #12
authored
159 aliased_actions[target] = args
4b6f538 @ryanb moving can definition into ability instance instead of class, this remov...
authored
160 end
161
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
162 private
163
c40490d @ryanb refactoring ability can? method - closes #12
authored
164 def aliased_actions
165 @aliased_actions ||= default_alias_actions
166 end
167
4b6f538 @ryanb moving can definition into ability instance instead of class, this remov...
authored
168 def default_alias_actions
169 {
170 :read => [:index, :show],
171 :create => [:new],
172 :update => [:edit],
173 }
174 end
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
175
c40490d @ryanb refactoring ability can? method - closes #12
authored
176 def expand_actions(actions)
177 [actions].flatten.map do |action|
178 if aliased_actions[action]
179 [action, *aliased_actions[action]]
180 else
181 action
182 end
183 end.flatten
184 end
185
186 def can_perform_action?(action, noun, defined_actions, defined_nouns, defined_block)
187 if defined_block.nil?
188 true
189 else
190 block_args = []
191 block_args << action if defined_actions.include?(:manage)
192 block_args << (noun.class == Class ? noun : noun.class) if defined_nouns.include?(:all)
193 block_args << (noun.class == Class ? nil : noun)
194 return defined_block.call(*block_args)
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
195 end
c40490d @ryanb refactoring ability can? method - closes #12
authored
196 end
197
198 def includes_action?(actions, action)
199 actions.include?(:manage) || actions.include?(action)
200 end
201
202 def includes_noun?(nouns, noun)
203 nouns.include?(:all) || nouns.include?(noun) || nouns.any? { |c| c.kind_of?(Class) && noun.kind_of?(c) }
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
204 end
0cfb8c7 @ryanb adding basic ability module
authored
205 end
206 end
Something went wrong with that request. Please try again.