Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 124 lines (71 sloc) 5.421 kB
0b15de7 Update README.rdoc
Nícolas Iensen authored
1 = CanCan
2 {<img src="https://fury-badge.herokuapp.com/rb/cancan.png" alt="Gem Version" />}[http://badge.fury.io/rb/cancan]
3 {<img src="https://secure.travis-ci.org/ryanb/cancan.png?branch=master" />}[http://travis-ci.org/ryanb/cancan]
4 {<img src="https://codeclimate.com/github/ryanb/cancan.png" />}[https://codeclimate.com/github/ryanb/cancan]
6c6a57b @ryanb adding documentation placeholder
authored
5
39bffe9 @ryanb fixing github links in readme
authored
6 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
7
6c3e87e @ryanb updating readme and documentation
authored
8 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
9
10
11 == Installation
12
2012311 @ryanb readme improvements
authored
13 In <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
14
6c3e87e @ryanb updating readme and documentation
authored
15 gem "cancan"
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
16
6c3e87e @ryanb updating readme and documentation
authored
17 In <b>Rails 2</b>, add this to your environment.rb file.
18dcf2a @ryanb mention Rails 3 installation in README - closes #56
authored
18
6c3e87e @ryanb updating readme and documentation
authored
19 config.gem "cancan"
18dcf2a @ryanb mention Rails 3 installation in README - closes #56
authored
20
6c3e87e @ryanb updating readme and documentation
authored
21 Alternatively, you can install it as a plugin.
28eaf1b @ryanb releasing gem v0.1.0
authored
22
6c3e87e @ryanb updating readme and documentation
authored
23 rails plugin install git://github.com/ryanb/cancan.git
b1d3d66 @ryanb filling readme
authored
24
25
f7480d1 @ryanb releasing gem v1.0.0 (backwards incompatible, see changelog)
authored
26 == Getting Started
b1d3d66 @ryanb filling readme
authored
27
2012311 @ryanb readme improvements
authored
28 CanCan expects a +current_user+ method to exist in the controller. First, 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
29
2012311 @ryanb readme improvements
authored
30
31 === 1. Define Abilities
32
33 User permissions are defined in an +Ability+ class. CanCan 1.5 includes a Rails 3 generator for creating this class.
b1d3d66 @ryanb filling readme
authored
34
120eafe @ryanb updating readme for 1.5
authored
35 rails g cancan:ability
25637bb @ryanb removing extra white space at end of lines
authored
36
c1979e8 @kimberninger Fixed a typo in README.rdoc
kimberninger authored
37 In Rails 2.3, just add a new class in `app/models/ability.rb` with the following contents:
0bbe2e1 @NickClark Clarify readme for rails 2.3 users
NickClark authored
38
39 class Ability
40 include CanCan::Ability
41
42 def initialize(user)
43 end
44 end
45
2012311 @ryanb readme improvements
authored
46 See {Defining Abilities}[https://github.com/ryanb/cancan/wiki/defining-abilities] for details.
47
48
49 === 2. Check Abilities & Authorization
b1d3d66 @ryanb filling readme
authored
50
120eafe @ryanb updating readme for 1.5
authored
51 The current user's permissions can then be checked using the <tt>can?</tt> and <tt>cannot?</tt> methods in the view and controller.
b1d3d66 @ryanb filling readme
authored
52
53 <% if can? :update, @article %>
54 <%= link_to "Edit", edit_article_path(@article) %>
55 <% end %>
56
39bffe9 @ryanb fixing github links in readme
authored
57 See {Checking Abilities}[https://github.com/ryanb/cancan/wiki/checking-abilities] for more information
283f58e @ryanb improving readme with links to wiki
authored
58
2012311 @ryanb readme improvements
authored
59 The <tt>authorize!</tt> method in the controller will raise an exception if the user is not able to perform the given action.
b1d3d66 @ryanb filling readme
authored
60
61 def show
62 @article = Article.find(params[:id])
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
authored
63 authorize! :read, @article
b1d3d66 @ryanb filling readme
authored
64 end
65
2012311 @ryanb readme improvements
authored
66 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 every action.
b1d3d66 @ryanb filling readme
authored
67
68 class ArticlesController < ApplicationController
f7480d1 @ryanb releasing gem v1.0.0 (backwards incompatible, see changelog)
authored
69 load_and_authorize_resource
25637bb @ryanb removing extra white space at end of lines
authored
70
b1d3d66 @ryanb filling readme
authored
71 def show
283f58e @ryanb improving readme with links to wiki
authored
72 # @article is already loaded and authorized
b1d3d66 @ryanb filling readme
authored
73 end
74 end
75
120eafe @ryanb updating readme for 1.5
authored
76 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
77
2012311 @ryanb readme improvements
authored
78
79 === 3. Handle Unauthorized Access
80
6c3e87e @ryanb updating readme and documentation
authored
81 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
82
83 class ApplicationController < ActionController::Base
f919ac5 @ryanb releasing gem v1.0.1
authored
84 rescue_from CanCan::AccessDenied do |exception|
b2028c8 @ryanb moving :alert into redirect_to call in documentation
authored
85 redirect_to root_url, :alert => exception.message
b1d3d66 @ryanb filling readme
authored
86 end
87 end
88
39bffe9 @ryanb fixing github links in readme
authored
89 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
90
b1d3d66 @ryanb filling readme
authored
91
79995e4 @ryanb adding Lock It Down section to readme
authored
92 === 4. Lock It Down
93
94 If you want to ensure authorization happens on every action in your application, add +check_authorization+ to your ApplicationController.
95
96 class ApplicationController < ActionController::Base
97 check_authorization
98 end
99
100 This will raise an exception if authorization is not performed in an action. If you want to skip this add +skip_authorization_check+ to a controller subclass. See {Ensure Authorization}[https://github.com/ryanb/cancan/wiki/Ensure-Authorization] for more information.
101
102
120eafe @ryanb updating readme for 1.5
authored
103 == Wiki Docs
37f482e @ryanb default ActiveRecordAdditions#can method action to :read and use 'sco…
authored
104
efa3ff1 @ryanb releasing 1.6.0
authored
105 * {Upgrading to 1.6}[https://github.com/ryanb/cancan/wiki/Upgrading-to-1.6]
120eafe @ryanb updating readme for 1.5
authored
106 * {Defining Abilities}[https://github.com/ryanb/cancan/wiki/Defining-Abilities]
107 * {Checking Abilities}[https://github.com/ryanb/cancan/wiki/Checking-Abilities]
108 * {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/Authorizing-Controller-Actions]
109 * {Exception Handling}[https://github.com/ryanb/cancan/wiki/Exception-Handling]
110 * {Changing Defaults}[https://github.com/ryanb/cancan/wiki/Changing-Defaults]
39bffe9 @ryanb fixing github links in readme
authored
111 * {See more}[https://github.com/ryanb/cancan/wiki]
df27653 @ryanb adding documentation for testing abilities - closes #6
authored
112
18b45d5 @ryanb adding Gemfile, to get specs running just bundle and rake - closes #163
authored
113
114 == Questions or Problems?
115
2012311 @ryanb readme improvements
authored
116 If you have any issues with CanCan which you cannot find the solution to in the documentation[https://github.com/ryanb/cancan/wiki], 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
117
2012311 @ryanb readme improvements
authored
118 To get the specs running you should call +bundle+ and then +rake+. See the {spec/README}[https://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
119
120
9d58226 @ryanb couple fixes in readme
authored
121 == Special Thanks
122
39bffe9 @ryanb fixing github links in readme
authored
123 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.