role_core 0.0.14 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c75876caf7676f2733564e2f0657b8625c798d29ee7de9e45a21bc66312e54d
-  data.tar.gz: 8bfb27b3b34481cb4cf566d3ff336e9450b45020a9109a201d7ac21e1e81194f
+  metadata.gz: 293e6cf06bd28270f0d19f2d20f57ea8387849067b324fcfea3fb627cb11c841
+  data.tar.gz: d1e32d432228cc32598e0309474179d7eaea3fc9734be71fc5f3717dd27b5ebb
 SHA512:
-  metadata.gz: 3c4d3a8e2c38049412bc12f8e048093710ee3f929d9f6cac96525de98ecd6e1f8b4851792e905f8c0c2cc7a467a04cff9512c03d435d585b1c29c3e04b4fb437
-  data.tar.gz: fb14f0557dc1b7349b69e647297ebe3033b97138665b2c5314cccf5456933552aa6b0b6c906f258abf7a55be3f05e59e0e1a77ad26714151738e32e431da66bf
+  metadata.gz: 8c6d27326c402fe05183bd06840c84621093905efb98beafc9969c1d8847e9268f26e990ffaec62436ae9bc8316d10afe4080dac7eda9abe6e374de6edc1042e
+  data.tar.gz: 74385a5cce46f0202ea498916fa7471added4ad6185b13f19d2dcd7eac1d2810c9d159a0f535bf691d80fe6c5ffdc0dfcd06d59260e582c48c824396c346a4aa

data/README.md

@@ -3,12 +3,93 @@ RoleCore
 
 RoleCore is a Rails engine which could provide essential industry of Role-based access control.
 
-<img width="550" alt="2018-03-12 10 12 21" src="https://user-images.githubusercontent.com/5518/37262401-e6c9d604-25dd-11e8-849d-7f7d923d5f18.png">
+## Demo
+
+The dummy app shows a simple multiple roles with CanCanCan integration including a management UI.
+
+<img width="550" alt="RoleCore dummy preview" src="https://user-images.githubusercontent.com/5518/37262401-e6c9d604-25dd-11e8-849d-7f7d923d5f18.png">
+
+Clone the repository.
+
+```sh
+$ git clone https://github.com/rails-engine/role_core.git
+```
+
+Change directory
+
+```sh
+$ cd role_core
+```
+
+Run bundler
+
+```sh
+$ bundle install
+```
 
-It's only provides the ability to define permissions and pre-made Role model.
+Preparing database
 
-In addition, it's not handle the authentication or authorization,
-you should integrate with CanCanCan, Pundit or other solutions by yourself.
+```sh
+$ bin/rails db:migrate
+```
+
+Start the Rails server
+
+```sh
+$ bin/rails s
+```
+
+Open your browser, and visit `http://localhost:3000`
+
+## What's does the RoleCore do
+
+### The role model
+
+The essence of RBAC is the role, despite your application, there are many possibilities: single-role, multi-roles, extendable-role and the role may associate to different kinds of resources (e.g: users and groups)
+
+RoleCore provides a essential definition of Role,
+you have to add association to adapt to your application,
+for example:
+
+- single-role: adding `one-to-many` association between Role and User
+- multi-roles: adding `many-to-many` association between Role and User
+- extendable-role: adding a self-association to Role
+- polymorphic-asscociated-role: consider using polymorphic association technique
+
+Although it's not out-of-box, but it will give you fully flexibility to suit your needs.
+
+### Permissions definition
+
+RoleCore provides a DSL (which inspired by [Redmine](https://github.com/redmine/redmine/blob/master/lib/redmine.rb#L76-L186)) that allows you define permissions for your application.
+
+Empowered by virtual model technique,
+these permissions your defined can be persisted through serialization,
+and can be used with OO-style, for example: `role.permissions.project.create?`
+
+There also support permission groups, and groups support nesting.
+
+I18n is supported too.
+
+In fact, the essence of permissions is Hash, keys are permissions, and values are booleans. so computing of permissions with many roles, can be understood as computing of Hashes.
+
+### Management UI
+
+Building a management UI is difficult, 
+but virtual model technique will translates permissions to a virtual model's (a class that conforms to ActiveModel) attributes, 
+and groups will translates to nested virtual models,
+that means you can use all Rails view helpers including the mighty form builder,
+and can benefit to Strong Parameter.
+
+The dummy app shows that rendering a permission list [only about 20 lines](https://github.com/rails-engine/role_core/blob/master/test/dummy/app/views/roles/_permissions.html.erb).
+
+If your application is API-only, you can simply dumping the role's permissions to JSON, and can still be benefit to StrongParameter.
+
+### Checking permission
+
+RoleCore **DOES NOT** handle the authentication or authorization directly,
+you have to integrate with CanCanCan, Pundit or other solutions by yourself.
+
+RoleCore can be working with CanCanCan, Pundit easily and happily.
 
 ## Installation
 
@@ -48,7 +129,7 @@ Run model generator
 $ bin/rails g role_core:model
 ```
 
-## Getting Start
+## Getting start
 
 ### Define permissions
 
@@ -57,11 +138,15 @@ checking it to know how to define permissions.
 
 In addition, there also includes a directive about how to integrate with CanCanCan.
 
-### Hook up to application
+#### I18n
 
-In order to obtain maximum customability, you need to hooking up role(s) to your user model by yourself.
+Check `config/locales/role_core.en.yml`
 
-#### For User who has single role
+### Hook application
+
+In order to obtain maximum customizability, you need to hooking up role(s) to your user model by yourself.
+
+#### User who has single role
 
 ##### Create `one-to-many` relationship between Role and User
 
@@ -77,7 +162,7 @@ Then do migrate
 $ bin/rails db:migrate
 ```
 
-Declare `a User belongs to a Role`
+Declare `a User belongs to a Role` association
 
 ```ruby
 class User < ApplicationRecord
@@ -87,7 +172,7 @@ class User < ApplicationRecord
 end
 ```
 
-Declare `a Role has many Users`
+Declare `a Role has many Users` association
 
 ```ruby
 class Role < RoleCore::Role
@@ -95,9 +180,9 @@ class Role < RoleCore::Role
 end
 ```
 
-##### Check permission
+##### Checking permission
 
-Permssions you've defined will translate to a virtual model (a Class which implemented ActiveModel interface),
+Permissions you've defined will translate to a virtual model (a Class which implemented ActiveModel interface),
 `permission` would be an attribute, `group` would be a nested virtual model (like ActiveRecord's `has_one` association).
 
 So you can simply check permission like:
@@ -128,7 +213,7 @@ user.permissions.project.read?
 
 _Keep in mind: fetching `role` will made a SQL query, you may need eager loading to avoid N+1 problem in some cases._
 
-#### For User who has multiple roles
+#### User who has multiple roles
 
 ##### Create `many-to-many` relationship between Role and User
 
@@ -144,7 +229,7 @@ Then do migrate
 $ bin/rails db:migrate
 ```
 
-Declare `a User has many Roles through RoleAssignments`
+Declare `a User has many Roles through RoleAssignments` association
 
 ```ruby
 class User < ApplicationRecord
@@ -155,7 +240,7 @@ class User < ApplicationRecord
 end
 ```
 
-Declare `a Role has many Users through RoleAssignments`
+Declare `a Role has many Users through RoleAssignments` association
 
 ```ruby
 class Role < RoleCore::Role
@@ -166,7 +251,7 @@ end
 
 ##### Check permission
 
-Permssions you've defined will translate to a virtual model (a Class which implemented ActiveModel interface),
+Permissions you've defined will translate to a virtual model (a Class which implemented ActiveModel interface),
 `permission` would be an attribute, `group` would be a nested virtual model (like ActiveRecord's `has_one` association).
 
 So you can simply check permission like:
@@ -211,63 +296,27 @@ Open your User model:
   Add a delegate to User model:
 
   ```ruby
-  delegate :permitted_permissions, to: :role
+  delegate :computed_permissions, to: :role
   ```
 
 - For a user who has multiple roles:
 
-  Add a `permitted_permissions` public method to User model:
+  Add a `computed_permissions` public method to User model:
 
   ```ruby
-  def permitted_permissions
-    roles.map(&:permitted_permissions).reduce(RoleCore::ComputedPermissions.new, &:concat)
+  def computed_permissions
+    roles.map(&:computed_permissions).reduce(RoleCore::ComputedPermissions.new, &:concat)
   end
   ```
 
-Open `app/models/ability.rb`, add `user.permitted_permissions.call(self, user)` to `initialize` method.
+Open `app/models/ability.rb`, add `user.computed_permissions.call(self, user)` to `initialize` method.
 
-You can check RoleCore's Demo (see below) for better understanding.
+You can check dummy app for better understanding.
 
 ### Management UI
 
 See [RolesController in dummy app](https://github.com/rails-engine/role_core/blob/master/test/dummy/app/controllers/roles_controller.rb)
-and relates [view](https://github.com/rails-engine/role_core/blob/master/test/dummy/app/views/roles/_form.html.erb).
-
-## Demo
-
-The dummy app shows a simple multiple roles with CanCanCan integration includes management UI.
-
-Clone the repository.
-
-```sh
-$ git clone https://github.com/rails-engine/role_core.git
-```
-
-Change directory
-
-```sh
-$ cd role_core
-```
-
-Run bundler
-
-```sh
-$ bundle install
-```
-
-Preparing database
-
-```sh
-$ bin/rails db:migrate
-```
-
-Start the Rails server
-
-```sh
-$ bin/rails s
-```
-
-Open your browser, and visit `http://localhost:3000`
+and relates [view](https://github.com/rails-engine/role_core/blob/master/test/dummy/app/views/roles/_form.html.erb) for details.
 
 ## Contributing
 
@@ -286,3 +335,5 @@ Please write unit test with your code if necessary.
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+

data/lib/role_core/concerns/models/role.rb

@@ -9,7 +9,7 @@ module RoleCore::Concerns
         validates :name,
                   presence: true
 
-        delegate :permitted_permissions, to: :permissions
+        delegate :computed_permissions, to: :permissions
 
         serialize :permissions, RoleCore.permission_set_class
       end

data/lib/role_core/permission_set.rb

@@ -6,10 +6,10 @@ module RoleCore
       attributes.select { |_, v| v }.keys
     end
 
-    def permitted_permissions(include_nested: true)
+    def computed_permissions(include_nesting: true)
       permissions = self.class.registered_permissions.slice(*permitted_permission_names).values
-      if include_nested && nested_attributes.any?
-        permissions.concat nested_attributes.values.map(&:permitted_permissions).flatten!
+      if include_nesting && nested_attributes.any?
+        permissions.concat nested_attributes.values.map(&:computed_permissions).flatten!
       end
 
       ComputedPermissions.new(permissions)

data/lib/role_core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RoleCore
-  VERSION = "0.0.14"
+  VERSION = "0.0.15"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: role_core
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.0.15
 platform: ruby
 authors:
 - jasl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-25 00:00:00.000000000 Z
+date: 2018-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails