Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 102 lines (62 sloc) 4.461 kb
6c6a57b @ryanb adding documentation placeholder
authored
1 = CanCan
2
39bffe9 @ryanb fixing github links in readme
authored
3 Wiki[https://github.com/ryanb/cancan/wiki] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan]
a13f78d @ryanb listing additional resources at top of readme page (including metrics…
authored
4
6c3e87e @ryanb updating readme and documentation
authored
5 CanCan is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in a single location (the +Ability+ class) and not duplicated across controllers, views, and database queries.
b1d3d66 @ryanb filling readme
authored
6
7
8 == Installation
9
6c3e87e @ryanb updating readme and documentation
authored
10 In <b>Rails 3</b>, add this to your Gemfile.
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
11
6c3e87e @ryanb updating readme and documentation
authored
12 gem "cancan"
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
13
6c3e87e @ryanb updating readme and documentation
authored
14 In <b>Rails 2</b>, add this to your environment.rb file.
18dcf2a @ryanb mention Rails 3 installation in README - closes #56
authored
15
6c3e87e @ryanb updating readme and documentation
authored
16 config.gem "cancan"
18dcf2a @ryanb mention Rails 3 installation in README - closes #56
authored
17
6c3e87e @ryanb updating readme and documentation
authored
18 Alternatively, you can install it as a plugin.
28eaf1b @ryanb releasing gem v0.1.0
authored
19
6c3e87e @ryanb updating readme and documentation
authored
20 rails plugin install git://github.com/ryanb/cancan.git
b1d3d66 @ryanb filling readme
authored
21
22
f7480d1 @ryanb releasing gem v1.0.0 (backwards incompatible, see changelog)
authored
23 == Getting Started
b1d3d66 @ryanb filling readme
authored
24
39bffe9 @ryanb fixing github links in readme
authored
25 CanCan expects a +current_user+ method to exist in controllers. If you have not already, set up some authentication (such as Authlogic[https://github.com/binarylogic/authlogic] or Devise[https://github.com/plataformatec/devise]). See {Changing Defaults}[https://github.com/ryanb/cancan/wiki/changing-defaults] if you need different behavior.
6c3e87e @ryanb updating readme and documentation
authored
26
27 Next create a class called +Ability+ in "models/ability.rb" or anywhere else in the load path. It should look similar to this.
b1d3d66 @ryanb filling readme
authored
28
29 class Ability
30 include CanCan::Ability
25637bb @ryanb removing extra white space at end of lines
authored
31
1edf583 @ryanb BACKWARDS INCOMPATIBLE: use Ability#initialize instead of 'prepare' t…
authored
32 def initialize(user)
b1d3d66 @ryanb filling readme
authored
33 if user.admin?
34 can :manage, :all
35 else
36 can :read, :all
37 end
38 end
39 end
40
39bffe9 @ryanb fixing github links in readme
authored
41 The +current_user+ is passed in to this method which is where the abilities are defined. See {Defining Abilities}[https://github.com/ryanb/cancan/wiki/defining-abilities] for what can go here.
b1d3d66 @ryanb filling readme
authored
42
e2910a7 @ryanb moving parts of the README into wiki pages
authored
43 The current user's permissions can then be accessed using the "can?" and "cannot?" methods in the view and controller.
b1d3d66 @ryanb filling readme
authored
44
45 <% if can? :update, @article %>
46 <%= link_to "Edit", edit_article_path(@article) %>
47 <% end %>
48
39bffe9 @ryanb fixing github links in readme
authored
49 See {Checking Abilities}[https://github.com/ryanb/cancan/wiki/checking-abilities] for more information
283f58e @ryanb improving readme with links to wiki
authored
50
51 The "authorize!" method in the controller will raise an exception if the user is not able to perform the given action.
b1d3d66 @ryanb filling readme
authored
52
53 def show
54 @article = Article.find(params[:id])
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored
55 authorize! :read, @article
b1d3d66 @ryanb filling readme
authored
56 end
57
b9995c6 @ryanb minor changes to readme
authored
58 Setting this for every action can be tedious, therefore the +load_and_authorize_resource+ method is provided to automatically authorize all actions in a RESTful style resource controller. It will use a before filter to load the resource into an instance variable and authorize it for each action.
b1d3d66 @ryanb filling readme
authored
59
60 class ArticlesController < ApplicationController
f7480d1 @ryanb releasing gem v1.0.0 (backwards incompatible, see changelog)
authored
61 load_and_authorize_resource
25637bb @ryanb removing extra white space at end of lines
authored
62
b1d3d66 @ryanb filling readme
authored
63 def show
283f58e @ryanb improving readme with links to wiki
authored
64 # @article is already loaded and authorized
b1d3d66 @ryanb filling readme
authored
65 end
66 end
67
39bffe9 @ryanb fixing github links in readme
authored
68 See {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/authorizing-controller-actions] for more information
283f58e @ryanb improving readme with links to wiki
authored
69
6c3e87e @ryanb updating readme and documentation
authored
70 If the user authorization fails, a <tt>CanCan::AccessDenied</tt> exception will be raised. You can catch this and modify its behavior in the +ApplicationController+.
b1d3d66 @ryanb filling readme
authored
71
72 class ApplicationController < ActionController::Base
f919ac5 @ryanb releasing gem v1.0.1
authored
73 rescue_from CanCan::AccessDenied do |exception|
6c3e87e @ryanb updating readme and documentation
authored
74 flash[:alert] = exception.message
b1d3d66 @ryanb filling readme
authored
75 redirect_to root_url
76 end
77 end
78
39bffe9 @ryanb fixing github links in readme
authored
79 See {Exception Handling}[https://github.com/ryanb/cancan/wiki/exception-handling] for more information.
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored
80
b1d3d66 @ryanb filling readme
authored
81
283f58e @ryanb improving readme with links to wiki
authored
82 == Additional Docs
37f482e @ryanb default ActiveRecordAdditions#can method action to :read and use 'sco…
authored
83
39bffe9 @ryanb fixing github links in readme
authored
84 * {Upgrading to 1.4}[https://github.com/ryanb/cancan/wiki/Upgrading-to-1.4]
85 * {Nested Resources}[https://github.com/ryanb/cancan/wiki/nested-resources]
86 * {Testing Abilities}[https://github.com/ryanb/cancan/wiki/testing-abilities]
87 * {Accessing Request Data}[https://github.com/ryanb/cancan/wiki/accessing-request-data]
88 * {Admin Namespace}[https://github.com/ryanb/cancan/wiki/admin-namespace]
89 * {See more}[https://github.com/ryanb/cancan/wiki]
df27653 @ryanb adding documentation for testing abilities - closes #6
authored
90
18b45d5 @ryanb adding Gemfile, to get specs running just bundle and rake - closes #163
authored
91
92 == Questions or Problems?
93
39bffe9 @ryanb fixing github links in readme
authored
94 If you have any issues with CanCan which you cannot find the solution to in the documentation, please add an {issue on GitHub}[https://github.com/ryanb/cancan/issues] or fork the project and send a pull request.
18b45d5 @ryanb adding Gemfile, to get specs running just bundle and rake - closes #163
authored
95
39bffe9 @ryanb fixing github links in readme
authored
96 To get the specs running you should call +bundle+ and then +rake+. Specs currently do not work in Ruby 1.9 due to the RR mocking framework. See the {spec/README}[httpss://github.com/ryanb/cancan/blob/master/spec/README.rdoc] for more information.
18b45d5 @ryanb adding Gemfile, to get specs running just bundle and rake - closes #163
authored
97
98
9d58226 @ryanb couple fixes in readme
authored
99 == Special Thanks
100
39bffe9 @ryanb fixing github links in readme
authored
101 CanCan was inspired by declarative_authorization[https://github.com/stffn/declarative_authorization/] and aegis[https://github.com/makandra/aegis]. Also many thanks to the CanCan contributors[https://github.com/ryanb/cancan/contributors]. See the CHANGELOG[https://github.com/ryanb/cancan/blob/master/CHANGELOG.rdoc] for the full list.
Something went wrong with that request. Please try again.