| | | ruby-toolbox
https://github.com/the-teacher/the_role_bootstrap3_ui
We are waiting for foundation version of UI
TheRole management web interface => localhost:3000/admin/roles |
puts following yields into your layout:
= yield :role_sidebar
= yield :role_main
gem 'the_role', '~> 2.5.2'
gem 'the_role_bootstrap3_ui'
Please read the_role_bootstrap3_ui docs to know more about assets
https://github.com/the-teacher/the_role_bootstrap3_ui
Please, before asking anything try to launch and play with the Dummy App in the spec folder. Maybe an example integration will be better than any documentation. Thank you!
- TheRole instead of CanCan?
- What does it mean semantic?
- Virtual sections and rules
- Using with Views
- Who is Administrator?
- Who is Moderator?
- Who is Owner?
# You can use any Bootstrap 3 version (CSS, LESS, SCSS)
gem 'bootstrap-sass', github: 'thomas-mcdonald/bootstrap-sass'
gem "the_role", "~> 2.0.0"
bundle
install note
bundle exec rails g the_role --help
Add a role_id:integer field to your User Model
def self.up
create_table :users do |t|
t.string :login
t.string :email
t.string :crypted_password
t.string :salt
# TheRole field
t.integer :role_id
t.timestamps
end
end
class User < ActiveRecord::Base
include TheRole::User
# or following alias for AR:
# has_role
# has_many :pages
end
Generate Role model
bundle exec rails g the_role install
or you can create Role model manually:
class Role < ActiveRecord::Base
include TheRole::Role
# or following alias for AR:
# acts_as_role
end
install TheRole migrations
rake the_role_engine:install:migrations
Invoke migrations
rake db:migrate
Create admin role
bundle exec rails g the_role admin
Makes any user as Admin
User.first.update( role: Role.with_name(:admin) )
include TheRoleController in your Application controller
class ApplicationController < ActionController::Base
include TheRole::Controller
protect_from_forgery
def access_denied
flash[:error] = t('the_role.access_denied')
redirect_to(:back)
end
end
config/routes.rb
concern :the_role, TheRole::AdminRoutes.new
namespace :admin do
concerns :the_role
end
create the_role config:
bundle exec rails g the_role config
config/initializers/the_role.rb
TheRole.configure do |config|
config.layout = :application
config.default_user_role = :user
config.access_denied_method = :access_denied # define it in ApplicationController
config.login_required_method = :authenticate_user! # devise auth method
# config.first_user_should_be_admin = false
# config.destroy_strategy = :restrict_with_exception # can be nil
end
class PagesController < ApplicationController
before_action :login_required, except: [:index, :show]
before_action :role_required, except: [:index, :show]
before_action :set_page, only: [:edit, :update, :destroy]
before_action :owner_required, only: [:edit, :update, :destroy]
def edit
# ONLY OWNER CAN EDIT THIS PAGE
end
private
def set_page
@page = Page.find params[:id]
# TheRole: You should define OWNER CHECK OBJECT
# When editable object was found
# You should define @owner_check_object before invoking **owner_required** method
@owner_check_object = @page
end
end
integration with Inhirited Resource
def owner_required
@owner_check_object = resource
super
end
TheRole, in contrast to CanCan, has a simple and predefined way to find the access state of the current role. If you don't want to create your own role scheme with CanCan Abilities - TheRole can be a great solution for you.
You can manage roles with a simple UI. TheRole's ACL structure is inspired by Rails' controllers, that's why it's so great for Rails applications.
Semantic - the science of meaning. Humans should be able to quickly understand what is happening in a role system.
Look at the next Role hash. If you can understand access rules - this authorization system is semantic.
role = {
'pages' => {
'index' => true,
'show' => true,
'new' => false,
'edit' => false,
'update' => false,
'destroy' => false
},
'articles' => {
'index' => true,
'show' => true
},
'twitter' => {
'button' => true,
'follow' => false
}
}
Usually, we use real names of controllers and actions for names of sections and rules:
@user.has_role?(:pages, :show)
But, also, you can use virtual names of sections, and virtual names of section's rules.
@user.has_role?(:twitter, :button)
@user.has_role?(:facebook, :like)
And you can use them as well as other access rules.
<% if @user.has_role?(:twitter, :button) %>
Twitter Button is Here
<% else %>
Nothing here :(
<% end %>
Administrator is the user who can access any section and rules of your application.
Administrator is the owner of any objects in your application.
Administrator is the user, who has a virtual section system and a rule administrator in the role-hash.
admin_role_fragment = {
:system => {
:administrator => true
}
}
Moderator is the user, who has access to any actions of some section(s).
Moderator is the owner of any objects of some class.
Moderator is the user, who has a virtual section moderator, with section name as rule name.
An example of a Moderator of Pages (controller) and Twitter (virtual section)
moderator_role_fragment = {
:moderator => {
:pages => true,
:blogs => false,
:twitter => true
}
}
Administrator is owner of any object in system.
Moderator of pages is owner of any page.
User is owner of objects, when Object#user_id == User#id.
# User's role
@user.role # => Role obj
Is a user Administrator?
@user.admin? => true | false
Is a user Moderator?
@user.moderator?(:pages) => true | false
@user.moderator?(:blogs) => true | false
@user.moderator?(:articles) => true | false
Has user got access to rule of section (action of controller)?
@user.has_role?(:pages, :show) => true | false
@user.has_role?(:blogs, :new) => true | false
@user.has_role?(:articles, :edit) => true | false
# return true if one of roles is true
@user.any_role?(pages: :show, posts: :show) => true | false
Is user Owner of object?
@user.owner?(@page) => true | false
@user.owner?(@blog) => true | false
@user.owner?(@article) => true | false
# Find a Role by name
@role = Role.with_name(:user)
@role.has?(:pages, :show) => true | false
@role.moderator?(:pages) => true | false
@role.admin? => true | false
# return true if one of roles is true
@role.any?(pages: :show, posts: :show) => true | false
# Create a section of rules
@role.create_section(:pages)
# Create rule in section (false value by default)
@role.create_rule(:pages, :index)
@role.to_hash => Hash
# JSON string
@role.to_json => String
# check method
@role.has_section?(:pages) => true | false
# set this rule on
@role.rule_on(:pages, :index)
# set this rule off
@role.rule_off(:pages, :index)
# Incoming hash is true-mask-hash
# All the rules of the Role will be reset to false
# Only rules from true-mask-hash will be set true
new_role_hash = {
:pages => {
:index => true,
:show => true
}
}
@role.update_role(new_role_hash)
# delete a section
@role.delete_section(:pages)
# delete a rule in section
@role.delete_rule(:pages, :show)
- 2.3.0 - Refactoring
- 2.1.0 - User#any_role? & Role#any?
- 2.0.3 - create role fix, cleanup
- 2.0.2 - code cleanup, readme
- 2.0.1 - code cleanup
- 2.0.0 - Rails 4 ready, configurable, tests
- 1.7.0 - mass assignment for User#role_id, doc, locales, changes in test app
- 1.6.9 - assets precompile addon
- 1.6.8 - doc, re dependencies
- 1.6.7 - Es locale (beta 0.2)
- 1.6.6 - Ru locale, localization (beta 0.1)
- 1.6.5 - has_section?, fixes, tests (alpha 0.3)
- 1.6.4 - En locale (alpha 0.2)
- 1.6.3 - notifications
- 1.6.0 - stabile release (alpha 0.1)
Ru, En (by me)
Es by @igmarin
zh_CN by @doabit & @linjunpop
PL by @egb3
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.