Skip to content
Newer
Older
100644 242 lines (231 sloc) 9.08 KB
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 16, 2009
1 module CanCan
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
2
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 17, 2009
3 # This module is automatically included into all controllers.
4 # It also makes the "can?" and "cannot?" methods available to all views.
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
5 module ControllerAdditions
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
6 module ClassMethods
ffa677b @ryanb Don't set resource instance variable if it has been set already - clo…
authored Dec 13, 2009
7 # Sets up a before filter which loads and authorizes the current resource. This performs both
8 # load_resource and authorize_resource and accepts the same arguments. See those methods for details.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
9 #
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
10 # class BooksController < ApplicationController
11 # load_and_authorize_resource
12 # end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
13 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
14 def load_and_authorize_resource(*args)
15 ControllerResource.add_before_filter(self, :load_and_authorize_resource, *args)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
16 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
17
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
18 # Sets up a before filter which loads the model resource into an instance variable.
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
19 # For example, given an ArticlesController it will load the current article into the @article
20 # instance variable. It does this by either calling Article.find(params[:id]) or
21 # Article.new(params[:article]) depending upon the action. It does nothing for the "index"
22 # action.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
23 #
ffa677b @ryanb Don't set resource instance variable if it has been set already - clo…
authored Dec 13, 2009
24 # Call this method directly on the controller class.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
25 #
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
26 # class BooksController < ApplicationController
27 # load_resource
28 # end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
29 #
ffa677b @ryanb Don't set resource instance variable if it has been set already - clo…
authored Dec 13, 2009
30 # A resource is not loaded if the instance variable is already set. This makes it easy to override
31 # the behavior through a before_filter on certain actions.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
32 #
ffa677b @ryanb Don't set resource instance variable if it has been set already - clo…
authored Dec 13, 2009
33 # class BooksController < ApplicationController
34 # before_filter :find_book_by_permalink, :only => :show
35 # load_resource
36 #
37 # private
38 #
39 # def find_book_by_permalink
40 # @book = Book.find_by_permalink!(params[:id)
41 # end
42 # end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
43 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
44 # If a name is provided which does not match the controller it assumes it is a parent resource. Child
45 # resources can then be loaded through it.
46 #
47 # class BooksController < ApplicationController
48 # load_resource :author
49 # load_resource :book, :through => :author
50 # end
51 #
52 # Here the author resource will be loaded before each action using params[:author_id]. The book resource
53 # will then be loaded through the @author instance variable.
54 #
55 # That first argument is optional and will default to the singular name of the controller.
56 # A hash of options (see below) can also be passed to this method to further customize it.
57 #
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
58 # See load_and_authorize_resource to automatically authorize the resource too.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
59 #
63634b4 @ryanb Adding :collection and :new options to load_resource method so we can…
authored Dec 13, 2009
60 # Options:
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
61 # [:+only+]
62 # Only applies before filter to given actions.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
63 #
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
64 # [:+except+]
65 # Does not apply before filter to given actions.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
66 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
67 # [:+through+]
68 # Load this resource through another one. This should match the name of the parent instance variable.
2a3dd85 @ryanb adding :name option to load_and_authorize_resource if it does not mat…
authored May 21, 2010
69 #
c9e0f4e @ryanb renaming :singular resource option to :singleton
authored Aug 6, 2010
70 # [:+singleton+]
71 # Pass +true+ if this is a singleton resource through a +has_one+ association.
84f4c90 @ryanb adding :singular option to support has_one associations in load/autho…
authored Aug 6, 2010
72 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
73 # [:+parent+]
74 # True or false depending on if the resource is considered a parent resource. This defaults to +true+ if a resource
75 # name is given which does not match the controller.
2a3dd85 @ryanb adding :name option to load_and_authorize_resource if it does not mat…
authored May 21, 2010
76 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
77 # [:+class+]
23a5888 @ryanb renaming :class option to :resource for load_and_authorize_resource w…
authored Apr 15, 2010
78 # The class to use for the model (string or constant).
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
79 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
80 # [:+instance_name+]
81 # The name of the instance variable to load the resource into.
82 #
236cece @ryanb adding :find_by option to load_resource - closes #19
authored Aug 6, 2010
83 # [:+find_by+]
84 # Find using a different attribute other than id. For example.
85 #
86 # load_resource :find_by => :permalink # will use find_by_permlink!(params[:id])
87 #
63634b4 @ryanb Adding :collection and :new options to load_resource method so we can…
authored Dec 13, 2009
88 # [:+collection+]
89 # Specify which actions are resource collection actions in addition to :+index+. This
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
90 # is usually not necessary because it will try to guess depending on if the id param is present.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
91 #
63634b4 @ryanb Adding :collection and :new options to load_resource method so we can…
authored Dec 13, 2009
92 # load_resource :collection => [:sort, :list]
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
93 #
63634b4 @ryanb Adding :collection and :new options to load_resource method so we can…
authored Dec 13, 2009
94 # [:+new+]
95 # Specify which actions are new resource actions in addition to :+new+ and :+create+.
96 # Pass an action name into here if you would like to build a new resource instead of
97 # fetch one.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
98 #
63634b4 @ryanb Adding :collection and :new options to load_resource method so we can…
authored Dec 13, 2009
99 # load_resource :new => :build
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
100 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
101 def load_resource(*args)
102 ControllerResource.add_before_filter(self, :load_resource, *args)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
103 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
104
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
105 # Sets up a before filter which authorizes the resource using the instance variable.
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
106 # For example, if you have an ArticlesController it will check the @article instance variable
107 # and ensure the user can perform the current action on it. Under the hood it is doing
108 # something like the following.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
109 #
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
110 # authorize!(params[:action].to_sym, @article || Article)
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
111 #
ffa677b @ryanb Don't set resource instance variable if it has been set already - clo…
authored Dec 13, 2009
112 # Call this method directly on the controller class.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
113 #
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
114 # class BooksController < ApplicationController
115 # authorize_resource
116 # end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
117 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
118 # If you pass in the name of a resource which does not match the controller it will assume
119 # it is a parent resource.
120 #
121 # class BooksController < ApplicationController
122 # authorize_resource :author
123 # authorize_resource :book
124 # end
125 #
126 # Here it will authorize :+show+, @+author+ on every action before authorizing the book.
127 #
128 # That first argument is optional and will default to the singular name of the controller.
129 # A hash of options (see below) can also be passed to this method to further customize it.
130 #
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
131 # See load_and_authorize_resource to automatically load the resource too.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
132 #
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
133 # Options:
134 # [:+only+]
135 # Only applies before filter to given actions.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
136 #
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
137 # [:+except+]
138 # Does not apply before filter to given actions.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
139 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
140 # [:+parent+]
141 # True or false depending on if the resource is considered a parent resource. This defaults to +true+ if a resource
142 # name is given which does not match the controller.
143 #
144 # [:+class+]
145 # The class to use for the model (string or constant). This passed in when the instance variable is not set.
146 # Pass +false+ if there is no associated class for this resource and it will use a symbol of the resource name.
2a3dd85 @ryanb adding :name option to load_and_authorize_resource if it does not mat…
authored May 21, 2010
147 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
148 # [:+instance_name+]
149 # The name of the instance variable for this resource.
2a3dd85 @ryanb adding :name option to load_and_authorize_resource if it does not mat…
authored May 21, 2010
150 #
25a1c55 @ryanb adding :through option to replace :nesting option and moving Resource…
authored Aug 5, 2010
151 def authorize_resource(*args)
152 ControllerResource.add_before_filter(self, :authorize_resource, *args)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
153 end
154 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
155
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
156 def self.included(base)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
157 base.extend ClassMethods
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - clo…
authored Nov 17, 2009
158 base.helper_method :can?, :cannot?
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
159 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
160
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
161 # Raises a CanCan::AccessDenied exception if the current_ability cannot
162 # perform the given action. This is usually called in a controller action or
163 # before filter to perform the authorization.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
164 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
165 # def show
166 # @article = Article.find(params[:id])
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
167 # authorize! :read, @article
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
168 # end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
169 #
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
170 # A :message option can be passed to specify a different message.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
171 #
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
172 # authorize! :read, @article, :message => "Not authorized to read #{@article.name}"
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
173 #
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
174 # You can rescue from the exception in the controller to customize how unauthorized
175 # access is displayed to the user.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
176 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
177 # class ApplicationController < ActionController::Base
ef22de6 @ryanb adding custom message argument to unauthorized! method - closes #18
authored Dec 15, 2009
178 # rescue_from CanCan::AccessDenied do |exception|
179 # flash[:error] = exception.message
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
180 # redirect_to root_url
181 # end
182 # end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
183 #
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
184 # See the CanCan::AccessDenied exception for more details on working with the exception.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
185 #
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
186 # See the load_and_authorize_resource method to automatically add the authorize! behavior
187 # to the default RESTful actions.
a5f838a @ryanb use I18n for unauthorization messages - closes #103
authored Sep 2, 2010
188 def authorize!(*args)
189 current_ability.authorize!(*args)
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
190 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
191
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored Apr 16, 2010
192 def unauthorized!(message = nil)
193 raise ImplementationRemoved, "The unauthorized! method has been removed from CanCan, use authorize! instead."
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
194 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
195
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 15, 2010
196 # Creates and returns the current user's ability and caches it. If you
197 # want to override how the Ability is defined then this is the place.
198 # Just define the method in the controller to change behavior.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
199 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
200 # def current_ability
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
201 # # instead of Ability.new(current_user)
202 # @current_ability ||= UserAbility.new(current_account)
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
203 # end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
204 #
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
205 # Notice it is important to cache the ability object so it is not
206 # recreated every time.
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
207 def current_ability
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
208 @current_ability ||= ::Ability.new(current_user)
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored Apr 15, 2010
209 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
210
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored Nov 19, 2009
211 # Use in the controller or view to check the user's permission for a given action
212 # and object.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
213 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
214 # can? :destroy, @project
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
215 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
216 # You can also pass the class instead of an instance (if you don't have one handy).
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
217 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
218 # <% if can? :create, Project %>
219 # <%= link_to "New Project", new_project_path %>
220 # <% end %>
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
221 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored Nov 19, 2009
222 # This simply calls "can?" on the current_ability. See Ability#can?.
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
223 def can?(*args)
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
224 current_ability.can?(*args)
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
225 end
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
226
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
227 # Convenience method which works the same as "can?" but returns the opposite value.
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
228 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
229 # cannot? :destroy, @project
dfd84a1 @ryanb improving inline documentation
authored May 21, 2010
230 #
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - clo…
authored Nov 17, 2009
231 def cannot?(*args)
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
232 current_ability.cannot?(*args)
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - clo…
authored Nov 17, 2009
233 end
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
234 end
235 end
236
aaed265 @ryanb turning into a funtioning Rails plugin
authored Nov 16, 2009
237 if defined? ActionController
238 ActionController::Base.class_eval do
239 include CanCan::ControllerAdditions
240 end
1edf583 @ryanb BACKWARDS INCOMPATIBLE: use Ability#initialize instead of 'prepare' t…
authored Nov 17, 2009
241 end
Something went wrong with that request. Please try again.