action_permission 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d598921d73d8ca53edf5154616e27108e9b9ef7
-  data.tar.gz: baaba6a7c5792c1f22433c768ab391cdec09cc0a
+  metadata.gz: ed9979494907e04aeaa65a5e7512e1eab1b4a2b0
+  data.tar.gz: 6e57506a7aaa20833b6f76cf56fe1eaa35a73b3b
 SHA512:
-  metadata.gz: 9de568d75f1b7871776526e385f35b5fa06e613cc78f745fcf7682b21f63e8ecab21639795572293c9a45f0a65429f1ebfb237da25231e55f6e9c2bdef9d9a89
-  data.tar.gz: 2cc23db2ada4942dde384df738c93168c69c4255b12e8a174dc4434bbef6048f59d3dbac791606a303387077402716718fb8ea43168faafe0bc039e9aecd1c99
+  metadata.gz: 8af6fe719487ddc81abdd1346ffafd9a4f291124d29e756e6abc70555839a16f5698e9360ac5dca13f2d6decd486300e4df11d2c8ddb7b256175840baabe08bb
+  data.tar.gz: 78390c60745981427dee34acc884c8b4479cdbec7e1f69de1ed62827a9470fe95848c1b64a924d55202843374de3ffa2667ccf7e516fec01cdded8ecdae16686

data/README.md

@@ -1,11 +1,9 @@
-__NOTICE: The gem as it stands is not production-ready.__
-_See [issues](https://github.com/mttdffy/action_permission/issues) for details_
-
-----
-
 # ActionPermission
 
-A permission structure for defining both action-based and attribute-based permissions for rails 3+ applications. 
+[![Gem Version](https://badge.fury.io/rb/action_permission.png)](http://badge.fury.io/rb/action_permission)
+[![Code Climate](https://codeclimate.com/github/mttdffy/action_permission.png)](https://codeclimate.com/github/mttdffy/action_permission)
+
+A permission structure for defining both action-based and attribute-based permissions for rails 4+ applications. 
 
 ## Installation
 
@@ -24,10 +22,10 @@ $ rails generate action_permission:install
 
 ## Usage
 
-ActionPermission assumes you have the concept of user roles. This can be any field of any name. It's core action is to load permissions for the controller handling the request, determine the user's access level, and call a method on the permission object that corresponds to that level. A permission file might look like this:
+ActionPermission assumes you have the concept of user roles/levels/segments. This can be any field on any object. It's core action is to load permissions that correspond to the controller handling the current request, determine the user's access level, and call a method on the permission object that corresponds to that level. A permission file might look like this:
 
 ```ruby
-class BookPermission < ApplicationPermission
+class BooksPermission < ApplicationPermission
 
   def params
     [:name, :author, :isbn, :page_count, :price]
@@ -36,8 +34,10 @@ class BookPermission < ApplicationPermission
   def guest
     allow [:index, :show]
   end
+  
+  match_with :guest, :member
 
-  def user
+  def editor
     allow [:index, :show, :new]
     allow [:create, :edit, :update, :destroy] do |user|
       @membership.id == user.id
@@ -53,8 +53,8 @@ class BookPermission < ApplicationPermission
 end
 ```
 
-- the `params` method can be used to define attributes allowed to be modified by that user level in addition to their allowed actions.
-- the `@membership` attribute is set on initialization based on the method handed to `authorize_with` in your `ApplicationController` (See 'Setup' below)
+- the `params` method can be used to define attributes allowed to be modified by that user level in addition to their allowed actions, which can be further refined for each level using `except` and `only options`.
+- the `@membership` attribute is set on initialization of the permission object. See setup for details in 'Setup'
 
 
 ## Setup
@@ -63,11 +63,11 @@ end
 $ rails generate action_permission:install
 ```
 
-This generator will creating the `app/permissions` directory along with a `application_perimission.rb` file.
+This generator creates the `app/permissions` directory along with a `application_perimission.rb` file.
 
-Permissions should be placed in the `app/permissions` directory. Each permission will typically extend from `ApplicationPermission`, allowing you to set default permissions for each role. 
+Permissions should be placed in the `app/permissions` directory and mimic the structure of your controllers. Each permission will typically extend from `ApplicationPermission`, allowing you to set default permissions for each role. 
 
-Additionally, the install generator will add some boilerplate code into your `ApplicationController` for setting up your application to work properly with ActionPermission. 
+Additionally, the install generator will add some boilerplate code into your `ApplicationController` required for setting up ActionPermission. It will look much like this:
 
 ```ruby
 #app/controllers/application_controller.rb
@@ -91,7 +91,11 @@ end
 
 This is a basic implementation that you can change and modify to work with your application's user role structure.
 
-Ultimately, ActionPermission looks to receive a string representing the name of the role/level of current user. It requires you to define a method on your `ApplicationController` to call when loading permissions. This method should return an object that can repond to a `#identify` method. `identify` method should return a string value of the current user's role
+Ultimately, ActionPermission looks to receive a string representing the name of the role/level of current user. It requires you to pass a method to `authorize_with` in your `ApplicationController` to call when loading permissions. 
+
+- This method should return an object that can repond to an `#identify` method. 
+- Object returned is set as `@membership` for use in `#allow` blocks (see example permission class above) 
+- `#identify` is expected to return a string or symbol representing the user's role/level. A method with a name matching this return value will be called on the permission object.
 
 ```ruby
 # app/models/user.rb
@@ -114,7 +118,7 @@ class ApplicationPermission < ActionPermission::Base
   
   def load(user)
     @membership = user
-    send @membership.role
+    send @membership.access_level
   end
 
 end
@@ -138,6 +142,70 @@ ApplicationController < ActionController::Base
 end
 ```
 
+You can set this at a global level in `ApplicationController`, or be specific about how it handles unauthorized access by checking `#authorized?` in an individual controller. Or both. 
+
+## Parameters
+
+You can enforce the user level's parameter access by using the `#allowed_params_for` method in each controller to retrieve the parameters to be passed into create or update methods.
+
+```ruby
+class BooksController < ApplicationController
+
+  # ...
+  def create
+    @book = Book.new(book_params)
+    if @book.save
+      redirect_to @book
+    else
+      render :new
+    end
+  end
+  
+  private
+  
+  def book_params
+    allowed_params_for :book, params 
+  end
+  
+  # ...
+
+end
+
+```
+
+The example above will load the `BooksPermission` class, call the method corresponding to the user's level, then filter the parameters in `params[:book]` based on the permission instance and return the allowed parameters. This uses and hooks into strong_parameters. 
+
+### `allowed_params_for(resource, params [, controller])`
+
+`#allowed_params_for` requires two arguments, and takes an options third. 
+
+Both `resource` and `controller` can be a string, symbol, Class, or Class instance. 
+
+By default, resource will be used to guess which permission to load, but you can explicity tell it which controller (thus corresponding permission file), you intend to check.  This comes into play when controllers and models are namespaced and may not be namespaced in the same way. 
+
+```ruby
+
+# would load BooksPermission 
+# and filter :book key of params
+allowed_params_for @book, params
+
+# would load Libraries::BooksPermission 
+# and filter :library_book key of params
+allowed_params_for 'library/book', params
+
+# would load permission corresponding to current controller
+# and filter :book key from params
+allowed_params_for :book, params, self
+
+# would load Admin::BooksPermission 
+# and filter :user_book key of params
+allowed_params_for 'user/book', params, Admin::BooksController
+
+# would load Library::BooksPermission 
+# and filter :user_book key of params
+allowed_params_for User::Book, params, 'library/books'
+```
+
 ## Generators
 
     rails g action_permission:install

data/lib/action_permission/controller.rb

@@ -53,4 +53,4 @@ module ActionPermission
 
 end
 
-ActionController::Base.send :include, ActionPermission::Controller if ENV['RAILS']
+ActionController::Base.send :include, ActionPermission::Controller if defined?(ActionController)

data/lib/action_permission/version.rb

@@ -1,3 +1,3 @@
 module ActionPermission
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_permission
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Matt Duffy
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-14 00:00:00.000000000 Z
+date: 2014-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails