the_role 1.5.0 → 1.5.1

data/README.md

@@ -69,15 +69,237 @@ current_user.has_role?(:facebook, :like)
 These sections and the rules are not associated with real controllers and actions.
 And you can use them as well as other access rules.
 
-### Who is the administrator?
+### Install and use
+
+``` ruby
+  gem 'the_role'
+```
+
+``` ruby
+  bundle install
+```
+
+Add **role_id:integer** to User Model Migration
+
+
+``` ruby
+rake the_role_engine:install:migrations
+  >> Copied migration 20111028145956_create_roles.rb from the_role_engine
+```
+
+``` ruby
+rails g model role --migration=false
+```
+
+``` ruby
+rake db:create && rake db:migrate
+```
+
+Creating roles for test (**not required**)
+
+``` ruby
+rake db:roles:test
+  >> Administrator, Moderator of pages, User, Demo
+```
+
+Define aliases method for correctly work TheRole's controllers
+
+**authenticate_user!** or any other method from your auth system
+
+**access_denied** or any other method for processing access denied situation
+
+**Example for Devise2**
+
+``` ruby
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+
+  def access_denied
+    render :text => 'access_denied: requires an role' and return
+  end
+
+  # define aliases for correctly work of TheRole admin panel
+  # *authenticate_user!* - method from Devise2
+  # *access_denied* - define it before alias_method
+  # before_filter :role_object_finder, :only   => [:edit, :update, :rebuild, :destroy]
+  alias_method :role_login_required, :authenticate_user!
+  alias_method :role_access_denied,  :access_denied
+
+end
+```
+
+Using with any controller
+
+``` ruby
+class PagesController < ApplicationController
+  # Devise2 and TheRole before_filters
+  before_filter :role_login_required, :except => [:index, :show]
+  before_filter :role_require,        :except => [:index, :show]
+
+  before_filter :find_page,           :only   => [:edit, :update, :destroy]
+  before_filter :owner_require,       :only   => [:edit, :update, :destroy]
+
+end
+```
+
+### WARNING! IT'S IMPORTANT
+
+When you checking **owner_require** - you should before this to define variable **@object_for_ownership_checking** in finder method.
+
+For example:
+
+``` ruby
+class PagesController < ApplicationController
+  before_filter :find_page,           :only   => [:edit, :update, :destroy]
+  before_filter :owner_require,       :only   => [:edit, :update, :destroy]
+  
+  private
+
+  def find_page
+    @page = Page.find params[:id]
+    @object_for_ownership_checking = @page
+  end
+end
+```
+
+### Who is the Administrator?
 
 Administrator - a user who can access any section and the rules of your application.
 The administrator is the owner of any objects in your application.
 Administrator - a user in the role-hash of which there is a section **system** and rule **administrator**.
 
 
+``` ruby
+admin_role_fragment = {
+  :system => {
+    :administrator => true
+  }
+}
+```
+
+### Who is the Moderator?
+
+Moderator - a user who can access any actions of sections.
+Moderator is the owner of any objects of this class.
+Moderator - user which has in a section **moderator** rule with name of real or virtual section (controller).
 
+There is role hash of Moderator of Pages (controller) and Twitter (virtual section)
+
+``` ruby
+moderator_role_fragment = {
+  :moderator => {
+    :pages   => true,
+    :blogs   => false,
+    :twitter => true
+  }
+}
+```
 
+### User methods
 
+Has a user an access to **action** of **section**?
 
+``` ruby
+current_user.has_role?(:pages,    :show)  => true | false
+current_user.has_role?(:blogs,    :new)   => true | false
+current_user.has_role?(:articles, :edit)  => true | false
+```
+
+Is it Moderator?
+
+``` ruby
+current_user.moderator?(:pages)           => true | false
+current_user.moderator?(:blogs)           => true | false
+current_user.moderator?(:articles)        => true | false
+```
+
+Is it Administrator?
+
+``` ruby
+current_user.admin?                       => true | false
+```
+
+Is it **Owner** of object?
+
+``` ruby
+current_user.owner?(@page)                => true | false
+current_user.owner?(@blog)                => true | false
+current_user.owner?(@article)             => true | false
+```
+
+### Role methods
+
+``` ruby
+# Find a Role by name
+@role.find_by_name(:user)
+```
+
+``` ruby
+# User Model like methods
+
+@role.has?(:pages, :show)       => true | false
+@role.moderator?(:pages)        => true | false
+@role.admin?                    => true | false
+```
+
+## CRUD API
+
+#### 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
+
+# YAML string
+@role.to_yaml => String
+
+# YAML string
+@role.to_s => String
+```
+
+#### UPDATE
+
+``` ruby
+# Incoming hash is true-mask-hash
+# All rules of Role will be reset to false
+# Only rules from true-mask-hash will be set on true
+new_role_hash = {
+  :pages => {
+    :index => true,
+    :show => true
+  }
+}
+
+@role.update_role(new_role_hash)
+```
+
+``` ruby
+# set this rule on true
+@role.rule_on(:pages, :index)
+```
+
+``` ruby
+# set this rule on false
+@role.rule_off(:pages, :index)
+```
+
+### DELETE
+
+``` ruby
+# delete a section
+@role.delete_section(:pages)
 
+# delete rule in section
+@role.delete_rule(:pages, :show)
+```

data/lib/the_role/version.rb

@@ -1,3 +1,3 @@
 module TheRole
-  VERSION = "1.5.0"
+  VERSION = "1.5.1"
 end

data/the_role.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Ilya N. Zykin"]
   s.email       = ["zykin-ilya@ya.ru"]
   s.homepage    = "https://github.com/the-teacher/the_role"
-  s.summary     = %q{TheRole - simple, but powerful role system}
-  s.description = %q{TheRole - simple, but powerful role system for ROR applications}
+  s.summary     = %q{TheRole, Role system with Web Interface, aka CanCan killer}
+  s.description = %q{TheRole, Role system with Web Interface, aka CanCan killer}
 
   s.rubyforge_project = "the_role"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: the_role
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-04-05 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: haml
-  requirement: &70445940 !ruby/object:Gem::Requirement
+  requirement: &73560920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70445940
+  version_requirements: *73560920
 - !ruby/object:Gem::Dependency
   name: sass
-  requirement: &70445730 !ruby/object:Gem::Requirement
+  requirement: &73560710 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70445730
+  version_requirements: *73560710
 - !ruby/object:Gem::Dependency
   name: sass-rails
-  requirement: &70445520 !ruby/object:Gem::Requirement
+  requirement: &73560500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70445520
+  version_requirements: *73560500
 - !ruby/object:Gem::Dependency
   name: coffee-rails
-  requirement: &70445310 !ruby/object:Gem::Requirement
+  requirement: &73560290 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,8 +54,8 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70445310
-description: TheRole - simple, but powerful role system for ROR applications
+  version_requirements: *73560290
+description: TheRole, Role system with Web Interface, aka CanCan killer
 email:
 - zykin-ilya@ya.ru
 executables: []
@@ -117,5 +117,5 @@ rubyforge_project: the_role
 rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
-summary: TheRole - simple, but powerful role system
+summary: TheRole, Role system with Web Interface, aka CanCan killer
 test_files: []