the_role 1.5.1 → 1.6.0

data/README.md

@@ -1,10 +1,14 @@
-# gem 'the_role'
+# gem 'the_role' (alpha v0.1)
 
-## Bye bye CanCan, I got The Role!
+| Bye bye CanCan, I got The Role! | Description |
+|:------------- |:-------------|
+| ![Bye bye CanCan, I got The Role!](https://github.com/the-teacher/the_role/raw/master/Bye_bye_CanCan_I_got_the_Role.png) | 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 store in database with JSON.<br><br>TheRole - Semantic, lightweight role system with an administrative interface.<br><br>Role is a two-level hash, consisting of the **sections** and nested **rules**.<br><br>**Section** may be associated with **controller** name.<br><br>**Rule** may be associated with **action** name.<br><br>Section can have many rules.<br><br>Rule can have **true** or **false** value<br><br>**Sections** and nested **Rules** provide **ACL** (**Access Control List**)<br><br>Role **stored in the database as JSON** string.<br><br>Using of hashes, makes role system extremely easy to configure and use.<br> |
 
-Semantic, lightweight role system with an administrative interface
+### GUI
 
-![TheSortableTree](https://github.com/the-teacher/the_role/raw/master/pic.png)
+| TheRole management web interface |
+|:-------------:|
+|![TheRole](https://github.com/the-teacher/the_role/raw/master/pic.png)|
 
 ## What does it mean semantic?
 
@@ -14,73 +18,55 @@ Look at hash. If you can understand access rules - this role system is semantica
 
 ``` ruby
 role = {
-  :pages => {
-    :index => true,
-    :show => true,
-    :new => false,
-    :edit => false,
-    :update => false,
-    :destroy => false
+  'pages' => {
+    'index'   => true,
+    'show'    => true,
+    'new'     => false,
+    'edit'    => false,
+    'update'  => false,
+    'destroy' => false
   },
-  :articles => {
-    :index => true,
-    :show => true
-  }
-  :twitter => {
-    :button => true,
-    :follow => false
+  'articles' => {
+    'index'  => true,
+    'show'   => true
+  },
+  'twitter'  => {
+    'button' => true,
+    'follow' => false
   }
 }
 ```
 
-### How it  works 
-
-Role - is a two-level hash, consisting of the sections and rules.
-
-**Section** may be associated with the name of a **controller**.
-
-**Rule** may be associated with the name of **action** in the controller.
-
-Section may contain a set of rules.
-
-**Rule in Section** can be set to **true** and **false**, this provide **ACL** (**Access Control List**)
-
-Role hash **stored in the database as YAML** string.
-Using of hashes, makes it extremely easy to configure access rules in the role.
-
 ### Virtual sections and rules
 
-Usually, we use real names of controllers as names of sections, and we use names of real actions in controllers as names of section's rules.
-
-Like this:
+Usually, we use real names of controllers and actions for names of sections and rules:
 
 ``` ruby
 current_user.has_role?(:pages, :show)
 ```
 
-But you can also create virtual sections and rules:
-
+But, also, you can use virtual names of sections, and virtual names of section's rules.
 
 ``` ruby
 current_user.has_role?(:twitter, :button)
 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.
 
-### Install and use
+# Install
 
 ``` ruby
   gem 'the_role'
 ```
 
 ``` ruby
-  bundle install
+  bundle
 ```
 
-Add **role_id:integer** to User Model Migration
+### Migrate
 
+Add **role_id:integer** to User Model Migration
 
 ``` ruby
 rake the_role_engine:install:migrations
@@ -95,18 +81,16 @@ rails g model role --migration=false
 rake db:create && rake db:migrate
 ```
 
-Creating roles for test (**not required**)
+### Fake roles for test (not required)
+
+Creating roles for test 
 
 ``` 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
+### Change your ApplicationController
 
 **Example for Devise2**
 
@@ -118,55 +102,48 @@ class ApplicationController < ActionController::Base
     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
+  alias_method :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]
+Define aliases method for correctly work TheRole's controllers
 
-end
-```
+**authenticate_user!** or any other method from your auth system
 
-### WARNING! IT'S IMPORTANT
+**access_denied** or any other method for processing access denied situation
 
-When you checking **owner_require** - you should before this to define variable **@object_for_ownership_checking** in finder method.
 
-For example:
+### Using with any controller
 
 ``` ruby
 class PagesController < ApplicationController
-  before_filter :find_page,           :only   => [:edit, :update, :destroy]
-  before_filter :owner_require,       :only   => [:edit, :update, :destroy]
-  
+  # Devise2 and TheRole before_filters
+  before_filter :login_required, :except => [:index, :show]
+  before_filter :role_required,  :except => [:index, :show]
+
+  before_filter :find_page,      :only   => [:edit, :update, :destroy]
+  before_filter :owner_required, :only   => [:edit, :update, :destroy]
+
   private
 
   def find_page
     @page = Page.find params[:id]
-    @object_for_ownership_checking = @page
+    @ownership_checking_object = @page
   end
 end
 ```
 
-### Who is the Administrator?
+**owner_required** method require **@ownership_checking_object** variable, with cheked object.
+
+### Who is 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**.
+Administrator it's a user who can access any section and the rules of your application.
+
+Administrator is the owner of any objects in your application.
+
+Administrator it's a user, which has virtual section **system** and rule **administrator** in the role-hash.
 
 
 ``` ruby
@@ -177,13 +154,15 @@ admin_role_fragment = {
 }
 ```
 
-### Who is the Moderator?
+### Who is Moderator?
+
+Moderator it's a user, which has access to any actions of some section(s).
 
-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).
+Moderator is's owner of any objects of some class.
 
-There is role hash of Moderator of Pages (controller) and Twitter (virtual section)
+Moderator it's a user, which has a virtual section **moderator**, with **section name** as rule name.
+
+There is Moderator of Pages (controller) and Twitter (virtual section)
 
 ``` ruby
 moderator_role_fragment = {
@@ -195,9 +174,17 @@ moderator_role_fragment = {
 }
 ```
 
-### User methods
+### Who is Owner?
+
+Administrator is owner of any object in system.
+
+Moderator of pages is owner of any page.
 
-Has a user an access to **action** of **section**?
+User is owner of object, when **Object#user_id == User#id**.
+
+# User Model methods
+
+Has a user an access to **rule** of **section** (action of controller)?
 
 ``` ruby
 current_user.has_role?(:pages,    :show)  => true | false
@@ -227,22 +214,25 @@ current_user.owner?(@blog)                => true | false
 current_user.owner?(@article)             => true | false
 ```
 
-### Role methods
+# Base Role methods
 
 ``` ruby
-# Find a Role by name
-@role.find_by_name(:user)
+# User's role
+@role = current_user.role
 ```
 
 ``` ruby
-# User Model like methods
+# Find a Role by name
+@role = Role.find_by_name(:user)
+```
 
+``` ruby
 @role.has?(:pages, :show)       => true | false
 @role.moderator?(:pages)        => true | false
 @role.admin?                    => true | false
 ```
 
-## CRUD API
+# CRUD API (for console users)
 
 #### CREATE
 
@@ -261,10 +251,10 @@ current_user.owner?(@article)             => true | false
 ``` ruby
 @role.to_hash => Hash
 
-# YAML string
-@role.to_yaml => String
+# JSON string
+@role.to_json => String
 
-# YAML string
+# JSON string
 @role.to_s => String
 ```
 

data/app/assets/javascripts/admin_the_role.js

@@ -0,0 +1,3 @@
+//= require jquery
+//= require jquery_ujs
+//= require bootstrap-dropdown

data/app/assets/javascripts/bootstrap-dropdown.js

@@ -0,0 +1,100 @@
+/* ============================================================
+ * bootstrap-dropdown.js v2.0.4
+ * http://twitter.github.com/bootstrap/javascript.html#dropdowns
+ * ============================================================
+ * Copyright 2012 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============================================================ */
+
+
+!function ($) {
+
+  "use strict"; // jshint ;_;
+
+
+ /* DROPDOWN CLASS DEFINITION
+  * ========================= */
+
+  var toggle = '[data-toggle="dropdown"]'
+    , Dropdown = function (element) {
+        var $el = $(element).on('click.dropdown.data-api', this.toggle)
+        $('html').on('click.dropdown.data-api', function () {
+          $el.parent().removeClass('open')
+        })
+      }
+
+  Dropdown.prototype = {
+
+    constructor: Dropdown
+
+  , toggle: function (e) {
+      var $this = $(this)
+        , $parent
+        , selector
+        , isActive
+
+      if ($this.is('.disabled, :disabled')) return
+
+      selector = $this.attr('data-target')
+
+      if (!selector) {
+        selector = $this.attr('href')
+        selector = selector && selector.replace(/.*(?=#[^\s]*$)/, '') //strip for ie7
+      }
+
+      $parent = $(selector)
+      $parent.length || ($parent = $this.parent())
+
+      isActive = $parent.hasClass('open')
+
+      clearMenus()
+
+      if (!isActive) $parent.toggleClass('open')
+
+      return false
+    }
+
+  }
+
+  function clearMenus() {
+    $(toggle).parent().removeClass('open')
+  }
+
+
+  /* DROPDOWN PLUGIN DEFINITION
+   * ========================== */
+
+  $.fn.dropdown = function (option) {
+    return this.each(function () {
+      var $this = $(this)
+        , data = $this.data('dropdown')
+      if (!data) $this.data('dropdown', (data = new Dropdown(this)))
+      if (typeof option == 'string') data[option].call($this)
+    })
+  }
+
+  $.fn.dropdown.Constructor = Dropdown
+
+
+  /* APPLY TO STANDARD DROPDOWN ELEMENTS
+   * =================================== */
+
+  $(function () {
+    $('html').on('click.dropdown.data-api', clearMenus)
+    $('body')
+      .on('click.dropdown', '.dropdown form', function (e) { e.stopPropagation() })
+      .on('click.dropdown.data-api', toggle, Dropdown.prototype.toggle)
+  })
+
+}(window.jQuery);

data/app/assets/stylesheets/admin_the_role.css

@@ -0,0 +1,7 @@
+/*
+ *= require 'mix'
+ *= require 'reset'
+ *= require 'custom'
+ *= require 'headers'
+ *= require 'role_set'
+*/

data/app/assets/stylesheets/alerts.less

@@ -0,0 +1,58 @@
+// ALERT STYLES
+// ------------
+
+// Base alert styles
+.alert {
+  padding: 8px 35px 8px 14px;
+  margin-bottom: @baseLineHeight;
+  text-shadow: 0 1px 0 rgba(255,255,255,.5);
+  background-color: @warningBackground;
+  border: 1px solid @warningBorder;
+  .border-radius(4px);
+  color: @warningText;
+}
+.alert-heading {
+  color: inherit;
+}
+
+// Adjust close link position
+.alert .close {
+  position: relative;
+  top: -2px;
+  right: -21px;
+  line-height: 18px;
+}
+
+// Alternate styles
+// ----------------
+
+.alert-success {
+  background-color: @successBackground;
+  border-color: @successBorder;  
+  color: @successText;
+}
+.alert-danger,
+.alert-error {
+  background-color: @errorBackground;
+  border-color: @errorBorder;
+  color: @errorText;
+}
+.alert-info {
+  background-color: @infoBackground;
+  border-color: @infoBorder;
+  color: @infoText;
+}
+
+// Block alerts
+// ------------------------
+.alert-block {
+  padding-top: 14px;
+  padding-bottom: 14px;
+}
+.alert-block > p,
+.alert-block > ul {
+  margin-bottom: 0;
+}
+.alert-block p + p {
+  margin-top: 5px;
+}

data/app/assets/stylesheets/button-groups.less

@@ -0,0 +1,191 @@
+// BUTTON GROUPS
+// -------------
+
+
+// Make the div behave like a button
+.btn-group {
+  position: relative;
+  .clearfix(); // clears the floated buttons
+  .ie7-restore-left-whitespace();
+}
+
+// Space out series of button groups
+.btn-group + .btn-group {
+  margin-left: 5px;
+}
+
+// Optional: Group multiple button groups together for a toolbar
+.btn-toolbar {
+  margin-top: @baseLineHeight / 2;
+  margin-bottom: @baseLineHeight / 2;
+  .btn-group {
+    display: inline-block;
+    .ie7-inline-block();
+  }
+}
+
+// Float them, remove border radius, then re-add to first and last elements
+.btn-group > .btn {
+  position: relative;
+  float: left;
+  margin-left: -1px;
+  .border-radius(0);
+}
+// Set corners individual because sometimes a single button can be in a .btn-group and we need :first-child and :last-child to both match
+.btn-group > .btn:first-child {
+  margin-left: 0;
+     -webkit-border-top-left-radius: 4px;
+         -moz-border-radius-topleft: 4px;
+             border-top-left-radius: 4px;
+  -webkit-border-bottom-left-radius: 4px;
+      -moz-border-radius-bottomleft: 4px;
+          border-bottom-left-radius: 4px;
+}
+// Need .dropdown-toggle since :last-child doesn't apply given a .dropdown-menu immediately after it
+.btn-group > .btn:last-child,
+.btn-group > .dropdown-toggle {
+     -webkit-border-top-right-radius: 4px;
+         -moz-border-radius-topright: 4px;
+             border-top-right-radius: 4px;
+  -webkit-border-bottom-right-radius: 4px;
+      -moz-border-radius-bottomright: 4px;
+          border-bottom-right-radius: 4px;
+}
+// Reset corners for large buttons
+.btn-group > .btn.large:first-child {
+  margin-left: 0;
+     -webkit-border-top-left-radius: 6px;
+         -moz-border-radius-topleft: 6px;
+             border-top-left-radius: 6px;
+  -webkit-border-bottom-left-radius: 6px;
+      -moz-border-radius-bottomleft: 6px;
+          border-bottom-left-radius: 6px;
+}
+.btn-group > .btn.large:last-child,
+.btn-group > .large.dropdown-toggle {
+     -webkit-border-top-right-radius: 6px;
+         -moz-border-radius-topright: 6px;
+             border-top-right-radius: 6px;
+  -webkit-border-bottom-right-radius: 6px;
+      -moz-border-radius-bottomright: 6px;
+          border-bottom-right-radius: 6px;
+}
+
+// On hover/focus/active, bring the proper btn to front
+.btn-group > .btn:hover,
+.btn-group > .btn:focus,
+.btn-group > .btn:active,
+.btn-group > .btn.active {
+  z-index: 2;
+}
+
+// On active and open, don't show outline
+.btn-group .dropdown-toggle:active,
+.btn-group.open .dropdown-toggle {
+  outline: 0;
+}
+
+
+
+// Split button dropdowns
+// ----------------------
+
+// Give the line between buttons some depth
+.btn-group > .dropdown-toggle {
+  padding-left: 8px;
+  padding-right: 8px;
+  .box-shadow(~"inset 1px 0 0 rgba(255,255,255,.125), inset 0 1px 0 rgba(255,255,255,.2), 0 1px 2px rgba(0,0,0,.05)");
+  *padding-top: 4px;
+  *padding-bottom: 4px;
+}
+.btn-group > .btn-mini.dropdown-toggle {
+  padding-left: 5px;
+  padding-right: 5px;
+}
+.btn-group > .btn-small.dropdown-toggle {
+  *padding-top: 4px;
+  *padding-bottom: 4px;
+}
+.btn-group > .btn-large.dropdown-toggle {
+  padding-left: 12px;
+  padding-right: 12px;
+}
+
+.btn-group.open {
+
+  // The clickable button for toggling the menu
+  // Remove the gradient and set the same inset shadow as the :active state
+  .dropdown-toggle {
+    background-image: none;
+    .box-shadow(~"inset 0 2px 4px rgba(0,0,0,.15), 0 1px 2px rgba(0,0,0,.05)");
+  }
+
+  // Keep the hover's background when dropdown is open
+  .btn.dropdown-toggle {
+    background-color: @btnBackgroundHighlight;
+  }
+  .btn-primary.dropdown-toggle {
+    background-color: @btnPrimaryBackgroundHighlight;
+  }
+  .btn-warning.dropdown-toggle {
+    background-color: @btnWarningBackgroundHighlight;
+  }
+  .btn-danger.dropdown-toggle {
+    background-color: @btnDangerBackgroundHighlight;
+  }
+  .btn-success.dropdown-toggle {
+    background-color: @btnSuccessBackgroundHighlight;
+  }
+  .btn-info.dropdown-toggle {
+    background-color: @btnInfoBackgroundHighlight;
+  }
+  .btn-inverse.dropdown-toggle {
+    background-color: @btnInverseBackgroundHighlight;
+  }
+}
+
+
+// Reposition the caret
+.btn .caret {
+  margin-top: 7px;
+  margin-left: 0;
+}
+.btn:hover .caret,
+.open.btn-group .caret {
+  .opacity(100);
+}
+// Carets in other button sizes
+.btn-mini .caret {
+  margin-top: 5px;
+}
+.btn-small .caret {
+  margin-top: 6px;
+}
+.btn-large .caret {
+  margin-top: 6px;
+  border-left-width:  5px;
+  border-right-width: 5px;
+  border-top-width:   5px;
+}
+// Upside down carets for .dropup
+.dropup .btn-large .caret {
+  border-bottom: 5px solid @black;
+  border-top: 0;
+}
+
+
+
+// Account for other colors
+.btn-primary,
+.btn-warning,
+.btn-danger,
+.btn-info,
+.btn-success,
+.btn-inverse {
+  .caret {
+    border-top-color: @white;
+    border-bottom-color: @white;
+    .opacity(75);
+  }
+}
+