Skip to content
Newer
Older
100644 191 lines (181 sloc) 6.74 KB
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 16, 2009
1 module CanCan
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 17, 2009
2
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.
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
9 #
10 # class BooksController < ApplicationController
11 # load_and_authorize_resource
12 # end
13 #
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
14 def load_and_authorize_resource(options = {})
23a5888 @ryanb renaming :class option to :resource for load_and_authorize_resource w…
authored Apr 15, 2010
15 ResourceAuthorization.add_before_filter(self, :load_and_authorize_resource, options)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
16 end
17
18 # Sets up a before filter which loads the appropriate model resource into an instance variable.
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.
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.
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
25 #
26 # class BooksController < ApplicationController
27 # load_resource
28 # end
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.
32 #
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
43 #
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
44 # See load_and_authorize_resource to automatically authorize the resource too.
63634b4 @ryanb Adding :collection and :new options to load_resource method so we can…
authored Dec 13, 2009
45 #
46 # Options:
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
47 # [:+only+]
48 # Only applies before filter to given actions.
49 #
50 # [:+except+]
51 # Does not apply before filter to given actions.
cd217eb @ryanb adding :nested option for load_resource - closes #10
authored Dec 13, 2009
52 #
53 # [:+nested+]
54 # Specify which resource this is nested under.
55 #
56 # load_resource :nested => :author
57 #
a75aee7 @ryanb Allowing :nested option to accept an array for deep nesting
authored Dec 13, 2009
58 # Deep nesting can be defined in an array.
59 #
60 # load_resource :nested => [:publisher, :author]
61 #
23a5888 @ryanb renaming :class option to :resource for load_and_authorize_resource w…
authored Apr 15, 2010
62 # [:+resource+]
63 # The class to use for the model (string or constant).
021f33c @ryanb Adding :class option to load_resource so one can customize which clas…
authored Dec 14, 2009
64 #
63634b4 @ryanb Adding :collection and :new options to load_resource method so we can…
authored Dec 13, 2009
65 # [:+collection+]
66 # Specify which actions are resource collection actions in addition to :+index+. This
67 # is usually not necessary because it will try to guess depending on if an :+id+
68 # is present in +params+.
69 #
70 # load_resource :collection => [:sort, :list]
71 #
72 # [:+new+]
73 # Specify which actions are new resource actions in addition to :+new+ and :+create+.
74 # Pass an action name into here if you would like to build a new resource instead of
75 # fetch one.
76 #
77 # load_resource :new => :build
021f33c @ryanb Adding :class option to load_resource so one can customize which clas…
authored Dec 14, 2009
78 #
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
79 def load_resource(options = {})
23a5888 @ryanb renaming :class option to :resource for load_and_authorize_resource w…
authored Apr 15, 2010
80 ResourceAuthorization.add_before_filter(self, :load_resource, options)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
81 end
82
83 # Sets up a before filter which authorizes the current resource using the instance variable.
84 # For example, if you have an ArticlesController it will check the @article instance variable
85 # and ensure the user can perform the current action on it. Under the hood it is doing
86 # something like the following.
87 #
88 # unauthorized! if cannot?(params[:action].to_sym, @article || Article)
89 #
ffa677b @ryanb Don't set resource instance variable if it has been set already - clo…
authored Dec 13, 2009
90 # Call this method directly on the controller class.
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
91 #
92 # class BooksController < ApplicationController
93 # authorize_resource
94 # end
95 #
96 # See load_and_authorize_resource to automatically load the resource too.
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
97 #
98 # Options:
99 # [:+only+]
100 # Only applies before filter to given actions.
101 #
102 # [:+except+]
103 # Does not apply before filter to given actions.
104 #
23a5888 @ryanb renaming :class option to :resource for load_and_authorize_resource w…
authored Apr 15, 2010
105 # [:+resource+]
106 # The class to use for the model (string or constant). Alternatively pass a symbol
107 # to represent a resource which does not have a class.
021f33c @ryanb Adding :class option to load_resource so one can customize which clas…
authored Dec 14, 2009
108 #
94e031b @ryanb Pass :only and :except options to before filters for load/authorize r…
authored Dec 13, 2009
109 def authorize_resource(options = {})
23a5888 @ryanb renaming :class option to :resource for load_and_authorize_resource w…
authored Apr 15, 2010
110 ResourceAuthorization.add_before_filter(self, :authorize_resource, options)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
111 end
112 end
113
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
114 def self.included(base)
a5f9882 @ryanb turning load and authorize resource methods into class methods which …
authored Dec 13, 2009
115 base.extend ClassMethods
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - clo…
authored Nov 17, 2009
116 base.helper_method :can?, :cannot?
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
117 end
118
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
119 # Raises the CanCan::AccessDenied exception. This is often used in a
120 # controller action to mark a request as unauthorized.
121 #
122 # def show
123 # @article = Article.find(params[:id])
124 # unauthorized! if cannot? :read, @article
125 # end
126 #
ef22de6 @ryanb adding custom message argument to unauthorized! method - closes #18
authored Dec 15, 2009
127 # The unauthorized! method accepts an optional argument which sets the
128 # message of the exception.
129 #
130 # You can rescue from the exception in the controller to define the behavior.
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
131 #
132 # class ApplicationController < ActionController::Base
ef22de6 @ryanb adding custom message argument to unauthorized! method - closes #18
authored Dec 15, 2009
133 # rescue_from CanCan::AccessDenied do |exception|
134 # flash[:error] = exception.message
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
135 # redirect_to root_url
136 # end
137 # end
138 #
139 # See the load_and_authorize_resource method to automatically add
140 # the "unauthorized!" behavior to a RESTful controller's actions.
ef22de6 @ryanb adding custom message argument to unauthorized! method - closes #18
authored Dec 15, 2009
141 def unauthorized!(message = "You are not authorized to access this page.")
142 raise AccessDenied, message
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
143 end
144
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 15, 2010
145 # Creates and returns the current user's ability and caches it. If you
146 # want to override how the Ability is defined then this is the place.
147 # Just define the method in the controller to change behavior.
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
148 #
149 # def current_ability
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
150 # # instead of Ability.new(current_user)
151 # @current_ability ||= UserAbility.new(current_account)
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
152 # end
153 #
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
154 # Notice it is important to cache the ability object so it is not
155 # recreated every time.
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
156 def current_ability
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
157 @current_ability ||= ::Ability.new(current_user)
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored Apr 15, 2010
158 end
159
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored Nov 19, 2009
160 # Use in the controller or view to check the user's permission for a given action
161 # and object.
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
162 #
163 # can? :destroy, @project
164 #
165 # You can also pass the class instead of an instance (if you don't have one handy).
166 #
167 # <% if can? :create, Project %>
168 # <%= link_to "New Project", new_project_path %>
169 # <% end %>
170 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored Nov 19, 2009
171 # This simply calls "can?" on the current_ability. See Ability#can?.
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
172 def can?(*args)
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
173 current_ability.can?(*args)
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
174 end
1034c81 @ryanb adding a before filter for loading and authorizing a resource
authored Nov 16, 2009
175
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored Nov 18, 2009
176 # Convenience method which works the same as "can?" but returns the opposite value.
177 #
178 # cannot? :destroy, @project
179 #
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - clo…
authored Nov 17, 2009
180 def cannot?(*args)
ef5900c @ryanb adding caching to current_ability class method, if you're overriding …
authored Apr 16, 2010
181 current_ability.cannot?(*args)
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - clo…
authored Nov 17, 2009
182 end
44b36ce @ryanb adding controller additions with basic behavior.
authored Nov 17, 2009
183 end
184 end
185
aaed265 @ryanb turning into a funtioning Rails plugin
authored Nov 16, 2009
186 if defined? ActionController
187 ActionController::Base.class_eval do
188 include CanCan::ControllerAdditions
189 end
1edf583 @ryanb BACKWARDS INCOMPATIBLE: use Ability#initialize instead of 'prepare' t…
authored Nov 17, 2009
190 end
Something went wrong with that request. Please try again.