README.md in rolify-3.3.0.rc4 vs README.md in rolify-3.3.0
- old
+ new
@@ -1,7 +1,8 @@
-# rolify [](http://badge.fury.io/rb/rolify) [](http://travis-ci.org/EppO/rolify) [](https://gemnasium.com/EppO/rolify) [](https://codeclimate.com/github/EppO/rolify)
+# rolify [](http://badge.fury.io/rb/rolify) [](http://travis-ci.org/EppO/rolify) [](https://gemnasium.com/EppO/rolify) [](https://codeclimate.com/github/EppO/rolify) [](https://coveralls.io/r/EppO/rolify)
+
Very simple Roles library without any authorization enforcement supporting scope on resource object.
Let's see an example:
```ruby
@@ -23,48 +24,54 @@
## Installation
In <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.
```ruby
- gem "rolify"
+gem "rolify"
```
## Getting Started
### 1. Generate Role Model
First, create your Role model and migration file using this generator:
```
- rails g rolify Role User
+rails g rolify Role User
```
+**NB** for versions of Rolify prior to 3.3, use:
+
+```
+rails g rolify:role Role User
+```
+
Role and User classes are the default. You can specify any Role class name you want. This is completly a new file so any name can do the job.
For the User class name, you would probably use the one provided by your authentication solution. rolify just adds some class methods in an existing User class.
If you want to use Mongoid instead of ActiveRecord, just add `--orm=mongoid` argument, and skip to step #3
### 2. Run the migration (only required when using ActiveRecord)
Let's migrate !
```
- rake db:migrate
+rake db:migrate
```
### 3.1 Configure your user model
This gem adds the `rolify` method to your User class. You can also specify optional callbacks on the User class for when roles are added or removed:
```ruby
- class User < ActiveRecord::Base
- rolify :before_add => :before_add_method
+class User < ActiveRecord::Base
+ rolify :before_add => :before_add_method
- def before_add_method(role)
- # do something before it gets added
- end
+ def before_add_method(role)
+ # do something before it gets added
end
+end
```
The `rolify` method accepts the following callback options:
- `before_add`
@@ -88,104 +95,107 @@
### 4. Add a role to a user
To define a global role:
```ruby
- user = User.find(1)
- user.add_role :admin
+user = User.find(1)
+user.add_role :admin
```
To define a role scoped to a resource instance
```ruby
- user = User.find(2)
- user.add_role :moderator, Forum.first
+user = User.find(2)
+user.add_role :moderator, Forum.first
```
To define a role scoped to a resource class
```ruby
- user = User.find(3)
- user.add_role :moderator, Forum
+user = User.find(3)
+user.add_role :moderator, Forum
```
That's it !
### 5. Role queries
To check if a user has a global role:
```ruby
- user = User.find(1)
- user.add_role :admin # sets a global role
- user.has_role? :admin
- => true
+user = User.find(1)
+user.add_role :admin # sets a global role
+user.has_role? :admin
+=> true
```
To check if a user has a role scoped to a resource instance:
```ruby
- user = User.find(2)
- user.add_role :moderator, Forum.first # sets a role scoped to a resource instance
- user.has_role? :moderator, Forum.first
- => true
- user.has_role? :moderator, Forum.last
- => false
+user = User.find(2)
+user.add_role :moderator, Forum.first # sets a role scoped to a resource instance
+user.has_role? :moderator, Forum.first
+=> true
+user.has_role? :moderator, Forum.last
+=> false
```
To check if a user has a role scoped to a resource class:
```ruby
- user = User.find(3)
- user.add_role :moderator, Forum # sets a role scoped to a resource class
- user.has_role? :moderator, Forum
- => true
- user.has_role? :moderator, Forum.first
- => true
- user.has_role? :moderator, Forum.last
- => true
+user = User.find(3)
+user.add_role :moderator, Forum # sets a role scoped to a resource class
+user.has_role? :moderator, Forum
+=> true
+user.has_role? :moderator, Forum.first
+=> true
+user.has_role? :moderator, Forum.last
+=> true
```
A global role overrides resource role request:
```ruby
- user = User.find(4)
- user.add_role :moderator # sets a global role
- user.has_role? :moderator, Forum.first
- => true
- user.has_role? :moderator, Forum.last
- => true
+user = User.find(4)
+user.add_role :moderator # sets a global role
+user.has_role? :moderator, Forum.first
+=> true
+user.has_role? :moderator, Forum.last
+=> true
```
### 6. Resource roles querying
Starting from rolify 3.0, you can search roles on instance level or class level resources.
#### Instance level
```ruby
- forum = Forum.first
- forum.roles
- # => [ list of roles that are only binded to forum instance ]
- forum.applied_roles
- # => [ list of roles binded to forum instance and to the Forum class ]
+forum = Forum.first
+forum.roles
+# => [ list of roles that are only binded to forum instance ]
+forum.applied_roles
+# => [ list of roles binded to forum instance and to the Forum class ]
```
#### Class level
```ruby
- Forum.with_role(:admin)
- # => [ list of Forum instances that has role "admin" binded to it ]
- Forum.with_role(:admin, current_user)
- # => [ list of Forum instances that has role "admin" binded to it and belongs to current_user roles ]
-
- Forum.find_roles
- # => [ list of roles that binded to any Forum instance or to the Forum class ]
- Forum.find_roles(:admin)
- # => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name ]
- Forum.find_roles(:admin, current_user)
- # => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name and belongs to current_user roles ]
+Forum.with_role(:admin)
+# => [ list of Forum instances that has role "admin" binded to it ]
+Forum.with_role(:admin, current_user)
+# => [ list of Forum instances that has role "admin" binded to it and belongs to current_user roles ]
+
+User.with_any_role(:user, :admin)
+# => [ list of User instances that has role "admin" or "user" binded to it ]
+
+Forum.find_roles
+# => [ list of roles that binded to any Forum instance or to the Forum class ]
+Forum.find_roles(:admin)
+# => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name ]
+Forum.find_roles(:admin, current_user)
+# => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name and belongs to current_user roles ]
```
## Resources
* [Wiki](https://github.com/EppO/rolify/wiki)
@@ -197,10 +207,14 @@
## Upgrade from previous versions
Please read the [upgrade instructions](UPGRADE.rdoc).
+## Known issues
+
+If you are using Mongoid and/or less-rails gem, please read [this](https://github.com/EppO/rolify/wiki/FAQ#when-i-start-rails-using-server-console-whatever-i-get-this-error)
+
## Questions or Problems?
-If you have any issue or feature request with/for rolify, please add an [issue on GitHub](https://github.com/EppO/rolify/issues) or fork the project and send a pull request.
+If you have any issue or feature request with/for rolify, please create an new [issue on GitHub](https://github.com/EppO/rolify/issues) **specifying the ruby runtime, rails and rolify versions you're using and the gems listed in your Gemfile**, or fork the project and send a pull request.
To get the specs running you should call `bundle` and then `rake`. See the spec/README for more information.