role_core 0.0.12 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 161464a27b8e4e9f59ca62b95a6c975fec056196b48d1fe0a80e2d15618a368e
-  data.tar.gz: 28f2cc4b103d2093893ce45a98ab91e63e878e4639889822eae5e710286660d3
+  metadata.gz: 2c75876caf7676f2733564e2f0657b8625c798d29ee7de9e45a21bc66312e54d
+  data.tar.gz: 8bfb27b3b34481cb4cf566d3ff336e9450b45020a9109a201d7ac21e1e81194f
 SHA512:
-  metadata.gz: 4aaf5fe44a10e9448faec6c6ba0316ba446641238bd3c1d2e99fd29a950d43398e56ce1483edb7c0cb63d597fcccbf71dddb27aecd5e89e4dc0b3a6bb0999298
-  data.tar.gz: 4a85faabeeccdd1b4b84459be9aea41459972edddddac5ce6dbcbb190084304f405380496cd731cf446ea2ae37a55ae04f02301b64e27fe997fa06e2b6d71412
+  metadata.gz: 3c4d3a8e2c38049412bc12f8e048093710ee3f929d9f6cac96525de98ecd6e1f8b4851792e905f8c0c2cc7a467a04cff9512c03d435d585b1c29c3e04b4fb437
+  data.tar.gz: fb14f0557dc1b7349b69e647297ebe3033b97138665b2c5314cccf5456933552aa6b0b6c906f258abf7a55be3f05e59e0e1a77ad26714151738e32e431da66bf

data/README.md

@@ -1,13 +1,14 @@
 RoleCore
 ====
 
-A Rails engine providing essential industry of Role-based access control.
+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">
 
-## Usage
+It's only provides the ability to define permissions and pre-made Role model.
 
-See demo for now.
+In addition, it's not handle the authentication or authorization,
+you should integrate with CanCanCan, Pundit or other solutions by yourself.
 
 ## Installation
 
@@ -17,13 +18,7 @@ Add this line to your Gemfile:
 gem 'role_core'
 ```
 
-Or you may want to include the gem directly from GitHub:
-
-```ruby
-gem 'role_core', github: 'rails-engine/role_core'
-```
-
-And then execute:
+Then execute:
 
 ```sh
 $ bundle
@@ -41,8 +36,207 @@ Then do migrate
 $ bin/rails db:migrate
 ```
 
+Run config generator
+
+```sh
+$ bin/rails g role_core:config
+```
+
+Run model generator
+
+```sh
+$ bin/rails g role_core:model
+```
+
+## Getting Start
+
+### Define permissions
+
+Permissions are defined in `config/initializers/role_core.rb`,
+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
+
+In order to obtain maximum customability, you need to hooking up role(s) to your user model by yourself.
+
+#### For User who has single role
+
+##### Create `one-to-many` relationship between Role and User
+
+Generate `one-to-many` migration, adding `role_id` to `User` model
+
+```sh
+$ bin/rails g migration AddRoleToUsers role:references
+```
+
+Then do migrate
+
+```sh
+$ bin/rails db:migrate
+```
+
+Declare `a User belongs to a Role`
+
+```ruby
+class User < ApplicationRecord
+  belongs_to :role
+
+  # ...
+end
+```
+
+Declare `a Role has many Users`
+
+```ruby
+class Role < RoleCore::Role
+  has_many :users
+end
+```
+
+##### Check permission
+
+Permssions 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:
+
+```ruby
+user.role.permissions.read_public?
+user.role.permissions.project.read? # `project` is a `group`
+```
+
+For better usage, you may delegate the `permissions` from `Role` model to `User`:
+
+```ruby
+class User < ApplicationRecord
+  belongs_to :role
+
+  delegate :permissions, to: :role
+
+  # ...
+end
+```
+
+Then you can
+
+```ruby
+user.permissions.read_public?
+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
+
+##### Create `many-to-many` relationship between Role and User
+
+Generate a `many-to-many` intervening model
+
+```sh
+$ bin/rails g model RoleAssignment user:references role:references
+```
+
+Then do migrate
+
+```sh
+$ bin/rails db:migrate
+```
+
+Declare `a User has many Roles through RoleAssignments`
+
+```ruby
+class User < ApplicationRecord
+  has_many :role_assignments, dependent: :destroy
+  has_many :roles, through: :role_assignments
+
+  # ...
+end
+```
+
+Declare `a Role has many Users through RoleAssignments`
+
+```ruby
+class Role < RoleCore::Role
+  has_many :role_assignments, dependent: :destroy
+  has_many :users, through: :role_assignments
+end
+```
+
+##### Check permission
+
+Permssions 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:
+
+```ruby
+user.roles.any? { |role| role.permissions.read_public? }
+user.roles.any? { |role| role.permissions.project.read? } # `project` is a `group`
+```
+
+For better usage, you could declare a `can?` helper method:
+
+```ruby
+class User < ApplicationRecord
+  has_many :role_assignments, dependent: :destroy
+  has_many :roles, through: :role_assignments
+
+  def can?(&block)
+    roles.map(&:permissions).any?(&block)
+  end
+
+  # ...
+end
+```
+
+Then you can
+
+```ruby
+user.can? { |permissions| permissions.read_public? }
+user.can? { |permissions| permissions.project.read? }
+```
+
+_Keep in mind: fetching `roles` will made a SQL query, you may need eager loading to avoid N+1 problem in some cases._
+
+### Integrate with CanCanCan
+
+Open `config/initializers/role_core.rb`, uncomment CanCanCan integration codes and follows samples to define permissions for CanCanCan
+
+Open your User model:
+
+- For a user who has single role:
+
+  Add a delegate to User model:
+
+  ```ruby
+  delegate :permitted_permissions, to: :role
+  ```
+
+- For a user who has multiple roles:
+
+  Add a `permitted_permissions` public method to User model:
+
+  ```ruby
+  def permitted_permissions
+    roles.map(&:permitted_permissions).reduce(RoleCore::ComputedPermissions.new, &:concat)
+  end
+  ```
+
+Open `app/models/ability.rb`, add `user.permitted_permissions.call(self, user)` to `initialize` method.
+
+You can check RoleCore's Demo (see below) 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

data/lib/generators/role_core/config/USAGE

@@ -0,0 +1,2 @@
+Description:
+  The role_core:config generator creates RoleCore initializer and locale in the config directory.

data/lib/generators/role_core/config/config_generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RoleCore
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+
+      def generate_config
+        copy_file "role_core.rb", "config/initializers/role_core.rb"
+        copy_file "role_core.en.yml", "config/locales/role_core.en.yml"
+      end
+    end
+  end
+end

data/lib/generators/role_core/config/templates/role_core.en.yml

@@ -0,0 +1,20 @@
+en:
+  role_core:
+    models: # Defined by `group` place here
+#      project: Project
+#      task: Task
+    attributes:
+#      global: # Top-level permissions
+#        foo: Foo
+#        bar: Bar
+#      project:
+#        create: New project
+#        destroy: Destroy project
+#        update: Edit project
+#        read: Read project
+#        read_public: Read public project
+#      task:
+#        create: New task
+#        destroy: Destroy task
+#        update: Edit task
+#        update_my_own: Edit my own task

data/lib/generators/role_core/config/templates/role_core.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Uncomment below if you want to integrate with CanCanCan
+#
+#   require "role_core/contrib/can_can_can_permission"
+#   RoleCore.permission_class = RoleCore::CanCanCanPermission
+
+RoleCore.permission_set_class.draw do
+  # Define permissions for the application. For example:
+  #
+  #   permission :foo, default: true # `default: true` means grant to user by default
+  #   permission :bar
+  #
+  # You can also group permissions by using `group`:
+  #
+  #   group :project do
+  #     permission :create
+  #     permission :destroy
+  #     permission :update
+  #     permission :read
+  #     permission :read_public
+  #
+  #     # `group` supports nesting
+  #     group :task do
+  #       permission :create
+  #       permission :destroy
+  #       permission :update
+  #       permission :read
+  #     end
+  #   end
+  #
+  # For CanCanCan integration, you can pass `model_name` for `group` or `permission`. For example:
+  #
+  #   group :project, model_name: "Project" do
+  #     permission :create
+  #     permission :destroy, model_name: 'Plan'
+  #   end
+  #
+  # That will translate to CanCanCan's abilities (if user has these permissions),
+  # the permission's name will be the action:
+  #
+  #   can :create, Project
+  #   can :destroy, Plan
+  #
+  # You can pass `priority` argument to `permission`
+  #
+  #   group :project, model_name: "Project" do
+  #     permission :read_public,
+  #     permission :read, priority: 1
+  #   end
+  #
+  # That will made 'read' prior than `read_public`.
+  #
+  # For CanCanCan's hash of conditions
+  # (see https://github.com/CanCanCommunity/cancancan/wiki/Defining-Abilities#hash-of-conditions)
+  # you can simply pass them as arguments for `permission` even with a block
+  #
+  #   group :task, model_name: "Task" do
+  #     permission :read_public, is_public: true
+  #     permission :update_my_own, action: :update, default: true do |user, task|
+  #       task.user_id == user.id
+  #     end
+  #   end
+  #
+  # Although permission's name will be CanCanCan's action by default,
+  # you can pass `action` argument to override it.
+  #
+  #   permission :read_public, action: :read, is_public: true
+  #
+end.finalize! # Call `finalize!` to freezing the definition, that's optional.

data/lib/generators/role_core/model/USAGE

@@ -0,0 +1,2 @@
+Description:
+  The role_core:model generator creates Role model for customizing in the app/models directory.

data/lib/generators/role_core/model/model_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RoleCore
+  module Generators
+    class ModelGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+
+      def generate_model
+        copy_file "role.rb", "app/models/role.rb"
+      end
+    end
+  end
+end

data/lib/generators/role_core/model/templates/role.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class Role < RoleCore::Role
+end

data/lib/role_core/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: role_core
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.14
 platform: ruby
 authors:
 - jasl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-22 00:00:00.000000000 Z
+date: 2018-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -44,7 +44,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
-description: A Rails engine providing essential industry of Role-based access control
+description: RoleCore is a Rails engine which could provide essential industry of
+  Role-based access control.
 email:
 - jasl9187@hotmail.com
 executables: []
@@ -57,6 +58,13 @@ files:
 - app/models/role_core/application_record.rb
 - app/models/role_core/role.rb
 - db/migrate/20170705174003_create_roles.rb
+- lib/generators/role_core/config/USAGE
+- lib/generators/role_core/config/config_generator.rb
+- lib/generators/role_core/config/templates/role_core.en.yml
+- lib/generators/role_core/config/templates/role_core.rb
+- lib/generators/role_core/model/USAGE
+- lib/generators/role_core/model/model_generator.rb
+- lib/generators/role_core/model/templates/role.rb
 - lib/role_core.rb
 - lib/role_core/computed_permissions.rb
 - lib/role_core/concerns/models/role.rb
@@ -90,5 +98,6 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: A Rails engine providing essential industry of Role-based access control
+summary: RoleCore is a Rails engine which could provide essential industry of Role-based
+  access control.
 test_files: []