will/cancan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

readme improvements

Browse Source
This commit is contained in:
Ryan Bates 2011-01-18 11:55:46 -08:00
parent 52b33589dc
commit 2012311c40
1 changed files with 17 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.rdoc
View File

@ -7,7 +7,7 @@ CanCan is an authorization library for Ruby on Rails which restricts what resour
== Installation == Installation
In <b>Rails 3</b>, add this to your Gemfile. In <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.
gem "cancan" gem "cancan"
@ -22,13 +22,19 @@ Alternatively, you can install it as a plugin.
== Getting Started == Getting Started
CanCan expects a +current_user+ method to exist in controllers. 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 to customize this behavior. 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.
Next, make an +Ability+ class. CanCan 1.5 includes a generator for this.
=== 1. Define Abilities
User permissions are defined in an +Ability+ class. CanCan 1.5 includes a Rails 3 generator for creating this class.
rails g cancan:ability rails g cancan:ability
This is where the user permission will be defined. See the comments in models/ability.rb and {Defining Abilities}[https://github.com/ryanb/cancan/wiki/defining-abilities] for details. See {Defining Abilities}[https://github.com/ryanb/cancan/wiki/defining-abilities] for details.
=== 2. Check Abilities & Authorization
The current user's permissions can then be checked using the <tt>can?</tt> and <tt>cannot?</tt> methods in the view and controller. The current user's permissions can then be checked using the <tt>can?</tt> and <tt>cannot?</tt> methods in the view and controller.
@ -38,14 +44,14 @@ The current user's permissions can then be checked using the <tt>can?</tt> and <
See {Checking Abilities}[https://github.com/ryanb/cancan/wiki/checking-abilities] for more information See {Checking Abilities}[https://github.com/ryanb/cancan/wiki/checking-abilities] for more information
The "authorize!" method in the controller will raise an exception if the user is not able to perform the given action. The <tt>authorize!</tt> method in the controller will raise an exception if the user is not able to perform the given action.
def show def show
@article = Article.find(params[:id]) @article = Article.find(params[:id])
authorize! :read, @article authorize! :read, @article
end end
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. 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.
class ArticlesController < ApplicationController class ArticlesController < ApplicationController
load_and_authorize_resource load_and_authorize_resource
@ -57,6 +63,9 @@ Setting this for every action can be tedious, therefore the +load_and_authorize_
See {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/authorizing-controller-actions] for more information. See {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/authorizing-controller-actions] for more information.
=== 3. Handle Unauthorized Access
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+. 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+.
class ApplicationController < ActionController::Base class ApplicationController < ActionController::Base
@ -82,9 +91,9 @@ See {Exception Handling}[https://github.com/ryanb/cancan/wiki/exception-handling
== Questions or Problems? == Questions or Problems?
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. 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.
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}[https://github.com/ryanb/cancan/blob/master/spec/README.rdoc] for more information. 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.
== Special Thanks == Special Thanks