the_role 2.5.4 → 3.0.0

data/README.md

@@ -1,541 +1,193 @@
-## TheRole - Authorization Gem for Ruby on Rails with administrative interface.
-
-[![Gem Version](https://badge.fury.io/rb/the_role.png)](http://badge.fury.io/rb/the_role) | [![Build Status](https://travis-ci.org/the-teacher/the_role.png?branch=master)](https://travis-ci.org/the-teacher/the_role) | [![Code Climate](https://codeclimate.com/github/the-teacher/the_role.png)](https://codeclimate.com/github/the-teacher/the_role) | [ruby-toolbox](https://www.ruby-toolbox.com/categories/rails_authorization)
-
-### Semantic, Flexible, Lightweight
+<h2 align="center" class='center' style="text-align:center">
+  TheRole 3.0
+</h2>
+
+<p align="center" class='center' style="text-align:center">
+  <b>Authorization gem for Ruby on Rails</b><br>
+  <i>with <a href="https://github.com/TheRole/TheRoleManagementPanelBootstrap3">Management Panel</a></i>
+</p>
+
+<p align="center" class='center' style="text-align:center">
+  <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/the_role.png" alt="TheRole. Authorization gem for Ruby on Rails with Administrative interface">
+</p>
+
+<p align="center" class='center' style="text-align:center">
+  <b>Semantic. Flexible. Lightweigh</b>
+</p>
+
+<div align="center" class='center' style="text-align:center">
+
+<a href="http://badge.fury.io/rb/the_role"><img src="https://badge.fury.io/rb/the_role.svg" alt="Gem Version" height="18"></a>
+&nbsp;
+<a href="https://travis-ci.org/TheRole/DummyApp"><img src="https://travis-ci.org/TheRole/DummyApp.svg?branch=master" alt="Build Status" height="18"></a>
+&nbsp;
+<a href="https://codeclimate.com/github/TheRole/TheRoleApi"><img src="https://codeclimate.com/github/TheRole/TheRoleApi/badges/gpa.svg" /></a>
+&nbsp;
+<a href="https://www.ruby-toolbox.com/categories/rails_authorization">ruby-toolbox</a>
+
+<p>
+  Strongly recommended <a href='https://github.com/TheRole/docs/blob/master/MigrationsFromV2.md'>to upgrade from TheRole2 to TheRole3</a>. Please, do it ASAP.
+</p>
+</div>
 
 ### INTRO
 
-<table>
-<tr>
-<th align="left">Bye bye CanCan, I got The Role!</th>
-<th align="left">Description</th>
-</tr>
-<tr>
-<td><img src="https://github.com/the-teacher/the_role/raw/master/Bye_bye_CanCan_I_got_the_Role.png" alt="Bye bye CanCan, I got The Role!"></td>
-<td>TheRole is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in with 2-level-hash, and stored in the database as a JSON string.<br><br>TheRole - Semantic, lightweight role system with an administrative interface.<br><br>Role is a two-level hash, consisting of the <b>sections</b> and nested <b>rules</b>.<br><br>A <b>Section</b> may be associated with a <b>controller</b> name.<br><br>A <b>Rule</b> may be associated with an <b>action</b> name.<br><br>A Section can have many rules.<br><br>A Rule can be <b>true</b> or <b>false</b>.<br><br><b>Sections</b> and nested <b>Rules</b> provide an <b>ACL</b> (<b>Access Control List</b>)<br><br><br>Using hashes, makes role system extremely easy to configure and use.<br></td>
-</tr>
-</table>  
+TheRole is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in with **2-level-hash**, and **stored in the database as a JSON string**.
 
-### GUI
+<p align="center" class='center' style="text-align:center">
+  <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/hash2string.png" alt="TheRole. Authorization gem for Ruby on Rails with Administrative interface">
+</p>
 
-:warning: UI moved in **the_role_bootstrap3_ui** gem
+Using hashes, makes role system extremely easy to configure and use
 
-https://github.com/the-teacher/the_role_bootstrap3_ui
+* Any Role is a two-level hash, consisting of the <b>sections</b> and nested <b>rules</b>
+* A <b>Section</b> may be associated with a <b>controller</b> name
+* A <b>Rule</b> may be associated with an <b>action</b> name
+* A Section can have many rules
+* A Rule can be <b>true</b> or <b>false</b>
+* <b>Sections</b> and nested <b>Rules</b> provide an <b>ACL</b> (<b>Access Control List</b>)
 
-We are waiting for **foundation** version of UI
+#### Management Panel
 
 <table>
 <tr>
-  <td>TheRole management web interface => localhost:3000/admin/roles</td>
+  <td>
+    <b>http://localhost:3000/admin/roles</b>
+  </td>
 </tr>
 <tr>
-  <td><img src="https://github.com/the-teacher/the_role/raw/master/pic.png" alt="TheRole"></td>
+  <td>
+    <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/gui.png?2" alt="TheRole GUI">
+  </td>
 </tr>
 </table>
 
-puts following yields into your layout:
-
-```ruby
-= yield :role_sidebar
-= yield :role_main
-```
-
-### Rails 4 version
-
-```
-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
-
-
-## If you have any questions
-
-Please, before asking anything try to launch and play with the **[Dummy App](spec/dummy_app)** in the spec folder. Maybe an example integration will be better than any documentation. Thank you!
-
-### Instalation
-
-* [INSTALL](#install)
-* [INTEGRATION](#integration)
-* [Configuration (optional)](#configuration)
-
-### Understanding
-
-* [TheRole instead of CanCan?](#therole-instead-of-cancan)
-* [What does it mean semantic?](#what-does-it-mean-semantic)
-* [Virtual sections and rules](#virtual-sections-and-rules)
-* [Using with Views](#using-with-views)
-* [Who is Administrator?](#who-is-administrator)
-* [Who is Moderator?](#who-is-moderator)
-* [Who is Owner?](#who-is-owner)
-
-### API
-
-* [User](#user)
-* [Role](#role)
-
-## Install
-
-```ruby
-# You can use any Bootstrap 3 version (CSS, LESS, SCSS)
-gem 'bootstrap-sass', github: 'thomas-mcdonald/bootstrap-sass'
-
-gem "the_role", "~> 2.0.0"
-```
-
-```ruby
-bundle
-```
-
-install note
-
-```
-bundle exec rails g the_role --help
-```
-
-### Change User migration
-
-Add a **role_id:integer** field to your User Model
-
-```ruby
-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
-```
-
-### Change User model
-
-```ruby
-class User < ActiveRecord::Base
-  include TheRole::User
-  # or following alias for AR:
-  # has_role
-
-  # has_many :pages
-end
-```
-
-### Create Role model
-
-Generate Role model
-
-```ruby
-bundle exec rails g the_role install
-```
-
-or you can create Role model manually:
-
-```ruby
-class Role < ActiveRecord::Base
-  include TheRole::Role
-  # or following alias for AR:
-  # acts_as_role
-end
-```
-
-install TheRole migrations
-
-```ruby
-rake the_role_engine:install:migrations
-```
-
-Invoke migrations
-
-```ruby
-rake db:migrate
-```
-
-### Create Admin
-
-Create admin role
-
-```
-bundle exec rails g the_role admin
-```
-
-Makes any user as Admin
-
-```
-User.first.update( role: Role.with_name(:admin) )
-```
-
-## Integration
-
-#### Change your ApplicationController
-
-**include TheRoleController** in your Application controller
-
-```ruby
-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
-```
-
-#### Mount routes
-
-config/routes.rb
-
-```ruby
-  concern :the_role, TheRole::AdminRoutes.new
-  
-  namespace :admin do
-    concerns :the_role
-  end
-```
-
-### Configuration
-
-create the_role config:
-
-```
-bundle exec rails g the_role config
-```
-
-**config/initializers/the_role.rb**
-
-```ruby
-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
-```
-
-#### Usage with any controller
-
-```ruby
-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**
-
-```ruby
-  def owner_required
-    @owner_check_object = resource
-    super
-  end
-```
-
-## Understanding
-
-#### TheRole instead of CanCan?
-
-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.
-
-#### What does semantic mean?
-
-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.
-
-```ruby
-role = {
-  'pages' => {
-    'index'   => true,
-    'show'    => true,
-    'new'     => false,
-    'edit'    => false,
-    'update'  => false,
-    'destroy' => false
-  },
-  'articles' => {
-    'index'  => true,
-    'show'   => true
-  },
-  'twitter'  => {
-    'button' => true,
-    'follow' => false
-  }
-}
-```
-
-#### Virtual sections and rules
-
-Usually, we use real names of controllers and actions for names of sections and rules:
-
-```ruby
-@user.has_role?(:pages, :show)
-```
-
-But, also, you can use virtual names of sections, and virtual names of section's rules.
-
-```ruby
-@user.has_role?(:twitter, :button)
-@user.has_role?(:facebook, :like)
-```
-
-And you can use them as well as other access rules.
-
-#### Usage within Views
-
-```ruby
-<% if @user.has_role?(:twitter, :button) %>
-  Twitter Button is Here
-<% else %>
-  Nothing here :(
-<% end %>
-```
-
-#### Who is Administrator?
-
-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.
-
-
-```ruby
-admin_role_fragment = {
-  :system => {
-    :administrator => true
-  }
-}
-```
-
-#### Who is Moderator?
-
-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)
-
-```ruby
-moderator_role_fragment = {
-  :moderator => {
-    :pages   => true,
-    :blogs   => false,
-    :twitter => true
-  }
-}
-```
-
-#### Who is Owner?
-
-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**.
-
-
-# API
-
-## User
-
-```ruby
-# User's role
-@user.role # => Role obj
-```
-
-Is a user Administrator?
-
-```ruby
-@user.admin?                       => true | false
-```
-
-Is a user Moderator?
-
-```ruby
-@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)?
-
-```ruby
-@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?
-
-```ruby
-@user.owner?(@page)                => true | false
-@user.owner?(@blog)                => true | false
-@user.owner?(@article)             => true | false
-```
-
-## Role
-
-```ruby
-# Find a Role by name
-@role = Role.with_name(:user)
-```
-
-```ruby
-@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
-
-```ruby
-# Create a section of rules
-@role.create_section(:pages)
-```
-
-```ruby
-# Create rule in section (false value by default)
-@role.create_rule(:pages, :index)
-```
-
-#### READ
-
-```ruby
-@role.to_hash => Hash
-
-# JSON string
-@role.to_json => String
-
-# check method
-@role.has_section?(:pages) => true | false
-```
-
-#### UPDATE
-
-```ruby
-# set this rule on
-@role.rule_on(:pages, :index)
-```
-
-```ruby
-# set this rule off
-@role.rule_off(:pages, :index)
-```
-
-```ruby
-# 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
-
-```ruby
-# delete a section
-@role.delete_section(:pages)
-
-# delete a rule in section
-@role.delete_rule(:pages, :show)
-```
-
-#### Changelog
-
-* 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)
-
-### i18n
-
-**Ru, En** (by me)
-
-**Es** by @igmarin
-
-**zh_CN** by @doabit & @linjunpop
-
-**PL** by @egb3
-
-### MIT-LICENSE
-
-##### Copyright (c) 2012-2014 [Ilya N.Zykin]
-
-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.
+**Import/Export operations provided via TheRole Management Panel.** If you have 2 Rails apps, based on TheRole - you can move roles between them via export/import abilities of TheRole Management Panel.
+It can be usefull for Rails apps based on one engine.
+
+<div align="center" class='center' style="text-align:center">
+  <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/import_export.png" alt="TheRole. Authorization gem for Ruby on Rails with Administrative interface">
+</div>
+
+#### Limitations by Design
+
+TheRole uses few conventions over configuration.
+It gives simplicity of code, but also some limitations.
+You have to know about them before using of TheRole:
+<a href="https://github.com/TheRole/docs/blob/master/Limitations.md">Limitations list</a>
+
+<hr>
+
+<div align="center" class='center' style="text-align:center">
+  <a href="https://github.com/TheRole/docs/blob/master/TheRoleInstallation.md">
+    <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/install.png?2" alt="TheRole. Installation">
+  </a>
+</div>
+
+<div align="center" class='center' style="text-align:center">
+  <a href="https://github.com/TheRole/docs/blob/master/TheRoleAPI.md">
+    <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/api.png" alt="TheRole API">
+  </a>
+</div>
+
+<div align="center" class='center' style="text-align:center">
+  <a href="https://github.com/TheRole/docs/blob/master/IntegrationWithRailsControllers.md">
+    <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/int_ctrl.png" alt="Integration with Rails controllers">
+  </a>
+</div>
+
+<div align="center" class='center' style="text-align:center">
+  <a href="https://github.com/TheRole/docs/blob/master/IntegrationWithRailsViews.md">
+    <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/int_views.png" alt="Integration with Rails views">
+  </a>
+</div>
+
+<div align="center" class='center' style="text-align:center">
+  <a href="https://github.com/TheRole/docs/blob/master/UsingWithStrongParameters.md">
+    <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/int_params.png" alt="Using with Strong Parameters">
+  </a>
+</div>
+
+<div align="center" class='center' style="text-align:center">
+  <a href="https://github.com/TheRole/docs/blob/master/TheRoleGuiInstallation.md">
+    <img src="https://raw.githubusercontent.com/TheRole/docs/master/images/install_gui.png" alt="TheRole GUI. Installation">
+  </a>
+</div>
+
+<hr>
+
+<div align="center" class='center' style="text-align:center">
+  <table>
+    <tbody>
+      <tr>
+        <td colspan="2">
+          <b>FAQ</b>
+        </td>
+      </tr>
+
+      <tr>
+        <td width="350px" valign="top" style='vertical-align:top'>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/FAQ.md#why-therole-was-created'>Why TheRole was created?</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/FAQ.md#who-is-administrator'>Who is Administrator?</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/FAQ.md#who-is-moderator'>Who is Moderator?</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/FAQ.md#who-is-owner'>Who is Owner?</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/Ownership.md'>Few words about Ownership</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/Customization.md'>Customization, Rake tasks, code generators</a></p>
+        </td>
+
+        <td width="350px" valign="top" style='vertical-align:top'>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/FAQ.md##what-does-it-mean-semantic'>What does it mean semantic?</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/FAQ.md#virtual-sections-and-rules'>Virtual sections and rules</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/Limitations.md'>Limitations</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/Contributing.md'>Contributing</a></p>
+          <p align="left" class="left" style="text-align:left"><a href='https://github.com/TheRole/docs/blob/master/MigrationsFromV2.md'>Migration form TheRole 2 to TheRole 3</a></p>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+<hr>
+
+### We need your feedback!
+
+If you have to say something about TheRole, or if you need help, there are few ways to contact us:
+
+0. SKYPE:    **ilya.killich**
+0. Email:    zykin-ilya@ya.ru
+0. TWITTER:  [@iam_teacher](https://twitter.com/iam_teacher)
+0. Hash tag: [#the_role](https://twitter.com/hashtag/the_role)
+0. Google group: [about the_role](https://groups.google.com/forum/#!forum/the_role)
+
+<hr>
+
+#### Test matrix
+
+* **RAILS:** 3.2.21, 4.0, 4.1, 4.2
+* **RUBY:** 1.9.3, 2.0, 2.1, 2.2
+* **DB**: sqlite, mysql, postgresql
+
+totally: 48 environments
+
+<hr>
+
+**Supported locales:**
+[the_role_api](https://github.com/TheRole/the_role_api/tree/master/config/locales) |
+[the_role_management_panel](https://github.com/TheRole/the_role_management_panel/tree/master/config/locales)
+(please, help us with them)
+<hr>
+
+### MIT License
+
+[MIT License](https://github.com/TheRole/docs/blob/master/LICENSE.md)
+Copyright (c) 2012-2015 [Ilya N.Zykin](https://github.com/the-teacher)
+
+#### Maintainers
+
+[@the-teacher](https://github.com/the-teacher),
+[@sedx](https://github.com/sedx),
+[@seuros](https://github.com/seuros)
+
+#### Contributors
+
+@igmarin, @doabit, @linjunpop, @egb3