Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

small updates to the README #366

Merged
merged 4 commits into from
Dec 14, 2016
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 28 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,35 +5,28 @@
[![Code Climate Badge](https://codeclimate.com/github/CanCanCommunity/cancancan.svg)](https://codeclimate.com/github/CanCanCommunity/cancancan)
[![Inch CI](http://inch-ci.org/github/CanCanCommunity/cancancan.svg)](http://inch-ci.org/github/CanCanCommunity/cancancan)

[Wiki](https://github.com/CanCanCommunity/cancancan/wiki) | [RDocs](http://rdoc.info/projects/CanCanCommunity/cancancan) | [Screencast](http://railscasts.com/episodes/192-authorization-with-cancan) | [IRC: #cancancan (freenode)](http://webchat.freenode.net/?channels=cancancan)
[Wiki](https://github.com/CanCanCommunity/cancancan/wiki) | [RDocs](http://rdoc.info/projects/CanCanCommunity/cancancan) | [Screencast](http://railscasts.com/episodes/192-authorization-with-cancan) | [Gitter](https://gitter.im/CanCanCommunity/cancancan)

CanCan is an authorization library for Ruby 2.0+ and Ruby on Rails 3+ 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.
CanCanCan is an authorization library for Ruby 2.0+ and Ruby on Rails 3+ which restricts what resources a given user is allowed to access.

## This is the master branch!
This branch represents work towards version 2.0. Please checkout the 1.x branch for the stable release. Use master at your own risk.

## Mission

This repo is a continuation of the dead [CanCan](https://github.com/ryanb/cancan) project. Our mission is to keep CanCan alive and moving forward, with maintenance fixes and new features. Pull Requests are welcome!

I am currently focusing on the 1.x branch for the immediate future, making sure it is up to date as well as ensuring compatibility with Rails 4+. I will take a look into the 2.x branch and try to see what improvements, reorganizations and redesigns Ryan was attempting and go forward from there.

Any help is greatly appreciated, feel free to submit pull-requests or open issues.
All permissions are defined in a single location (the `Ability` class) and not duplicated across controllers, views, and database queries.


## Installation

Add this to your Gemfile:

gem 'cancancan', '~> 1.10'
gem 'cancancan'

and run the `bundle install` command.

## Getting Started

CanCanCan 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/CanCanCommunity/cancancan/wiki/changing-defaults) if you need different behavior.
CanCanCan expects a `current_user` method to exist in the controller.
First, set up some authentication (such as [Devise](https://github.com/plataformatec/devise) or [Authlogic](https://github.com/binarylogic/authlogic)).
See [Changing Defaults](https://github.com/CanCanCommunity/cancancan/wiki/changing-defaults) if you need a different behavior.

When using [rails-api](https://github.com/rails-api/rails-api), you have to manually include the controller methods for CanCan:
When using [rails-api](https://github.com/rails-api/rails-api), you have to manually include the controller methods for CanCanCan:
```ruby
class ApplicationController < ActionController::API
include CanCan::ControllerAdditions
Expand All @@ -42,7 +35,7 @@ end

### 1. Define Abilities

User permissions are defined in an `Ability` class. CanCan 1.5 includes a Rails 3 and 4 generator for creating this class.
User permissions are defined in an `Ability` class.

rails g cancan:ability

Expand All @@ -51,7 +44,7 @@ See [Defining Abilities](https://github.com/CanCanCommunity/cancancan/wiki/defin

### 2. Check Abilities & Authorization

The current user's permissions can then be checked using the `can?` and `cannot?` methods in the view and controller.
The current user's permissions can then be checked using the `can?` and `cannot?` methods in views and controllers.

```erb
<% if can? :update, @article %>
Expand All @@ -70,7 +63,8 @@ def show
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 action to load the resource into an instance variable and authorize it for every 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 action to load the resource into an instance variable and authorize it for every action.

```ruby
class ArticlesController < ApplicationController
Expand All @@ -89,7 +83,7 @@ See [Authorizing Controller Actions](https://github.com/CanCanCommunity/cancanca

When using `strong_parameters` or Rails 4+, you have to sanitize inputs before saving the record, in actions such as `:create` and `:update`.

For the `:update` action, CanCan will load and authorize the resource but *not* change it automatically, so the typical usage would be something like:
For the `:update` action, CanCanCan will load and authorize the resource but *not* change it automatically, so the typical usage would be something like:

```ruby
def update
Expand Down Expand Up @@ -136,7 +130,7 @@ class ArticlesController < ApplicationController
end
```

You can also use a string that will be evaluated in the context of the controller using `instance_eval` and needs to contain valid Ruby code. This does come in handy when using a PermittedParams class as suggested in Railscast 371:
You can also use a string that will be evaluated in the context of the controller using `instance_eval` and needs to contain valid Ruby code.

load_and_authorize_resource param_method: 'permitted_params.article'

Expand Down Expand Up @@ -188,7 +182,17 @@ This will raise an exception if authorization is not performed in an action. If
* [Changing Defaults](https://github.com/CanCanCommunity/cancancan/wiki/Changing-Defaults)
* [See more](https://github.com/CanCanCommunity/cancancan/wiki)

## Mission

This repo is a continuation of the dead [CanCan](https://github.com/ryanb/cancan) project.
Our mission is to keep CanCan alive and moving forward, with maintenance fixes and new features.
Pull Requests are welcome!

Any help is greatly appreciated, feel free to submit pull-requests or open issues.


## Questions?

If you have any question or doubt regarding CanCanCan which you cannot find the solution to in the [documentation](https://github.com/CanCanCommunity/cancancan/wiki) or our [mailing list](http://groups.google.com/group/cancancan), please [open a question on Stackoverflow](http://stackoverflow.com/questions/ask?tags=cancancan) with tag [cancancan](http://stackoverflow.com/questions/tagged/cancancan)

## Bugs?
Expand All @@ -209,4 +213,7 @@ See the [CONTRIBUTING](https://github.com/CanCanCommunity/cancancan/blob/develop

## Special Thanks

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/CanCanCommunity/cancancan/contributors). See the [CHANGELOG](https://github.com/CanCanCommunity/cancancan/blob/master/CHANGELOG.rdoc) for the full list.
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/CanCanCommunity/cancancan/contributors).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would be CanCanCan contributors

See the [CHANGELOG](https://github.com/CanCanCommunity/cancancan/blob/master/CHANGELOG.rdoc) for the full list.