adeia 0.10.5 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fbdf51a3d2163fc183b52129acad7c9006398c25
-  data.tar.gz: 31e48a7ee399b4104016ba87b3491b4c4ae67701
+  metadata.gz: 4a1ebe192b9a6f72013ede46d4c0c4e0c5216948
+  data.tar.gz: 10f965b7685d483496fc0a774e888572dcc2532e
 SHA512:
-  metadata.gz: 51950fe0201a51b93577e3aa7bbecf28cdf1baa8e293c02cb5d7739da42702a190ae907b76162d679786f990708b5bfb107f8edb3683c011e6e4e80b68fce9e3
-  data.tar.gz: a276223d46974bbe5327ad91d90b84a8c701faf37bdc5068ef8b1575fe65ad3d01ff467b15fd5230a694db253137780f25d2321b761d496d106c1eda9c095148
+  metadata.gz: c9f8cef57a7f79abc2c08ca7b113a8da305aecfdabdf064e817dc1b9ef3f1f22e56d85ddabbd6f8e3437ef8da55bfda62f42a69394c86f6ca3d1cf3ee62a484e
+  data.tar.gz: 00af089afb586476ea97bf640fe32901da4a3a2ae9cdb4f7b911e052007e884e8aa737bfb5fab5d2fb18317f9401c85d0899a24b8a709cdba96ca0b31f8cdaf0

data/README.md

@@ -2,9 +2,145 @@
 
 An authorization gem for Rails that allows you to have the complete control of your app.
 
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'adeia'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install adeia
+
+Then include the engine's routes in your `routes.rb`. The URL on which you mount the engine is up to you.
+
+```ruby
+# routes.rb
+
+mount Adeia::Engine => "/adeia"
+```
+
 ## Requirements
 
 Requires a User model with:
 
 * An method `name`, returning the name of the user.
-* A column `remember_token`, containing a generated token. It is used for the authentification.
+* A column `remember_token`, containing a generated token used for the authentification.
+
+## Documentation
+
+### Authentification
+
+Adeia provides methods to sign in and out, to get or set the current user and to check if a user is signed in.
+
+```ruby
+
+# sign in an user
+sign_in @user
+# alternatively, sign in permanently
+sign_in @user, permanent: true
+
+# get and set the connected user
+current_user # => #<User>
+current_user = @an_other_user
+
+# check if the user is signed in
+if signed_in?
+  # Do stuff
+end
+
+```
+
+### Authorization
+
+There are four different authorization methods at action-level.
+
+`require_login!` checks if the user is signed in. It raises the exception `LoginRequired` if not.
+
+```ruby
+def index
+  require_login!
+  @events = Event.all
+end
+```
+
+`authorize!` checks if the user has the permissions to access the action. It raises `AccessDenied` if not.
+
+```ruby
+def new
+  authorize!
+  @event = Event.new
+end
+```
+
+`load_and_authorize!` loads the suitable record and checks if the user has the permissions to access the action, taking into account the loaded record. It raises `AccessDenied` if not.
+The method returns the record, but it also automatically set an instance variable named after the model.
+
+```ruby
+def edit
+  @event = load_and_authorize!
+  # assignation is optional here
+end
+```
+
+`authorize_and_load_records!` loads the records taking into account the user's permissions. It raises `AccessDenied` if the user hasn't access to any records.
+
+```ruby
+def index
+  @events = authorize_and_load_records!
+  # assignation is optional here
+end
+```
+
+By default, the methods (except `require_login!`) use the following parameters:
+
+* controller: the controller's name
+* action: the action's name
+* token: GET parameter `token`
+* resource: fetch the resource from controller's name
+
+You can override those parameters when invoking the method:
+
+```ruby
+def index
+  authorize!(controller: 'events', action: 'new')
+end
+```
+Adeia also provide controller-level methods to keep your code DRY.
+
+`require_login` adds the `require_login!` method to the controller's actions.
+
+`load_and_authorize` adds the suitable methods to the controller's actions:
+
+* index: `authorize_and_load_records!`
+* show, edit, update, destroy: `load_and_authorize!`
+* new, create, other actions: `authorize!`
+
+The two controller-level methods accepts the restricting parameters `only` and `except`.
+
+```ruby
+class EventsController < ApplicationController
+
+  require_login only: [:postpone]
+  load_and_authorize, except: [:postpone]
+
+  def index; end
+
+  def new; end
+
+  def create; end
+
+  def postpone; end
+
+end
+```
+
+### Other methods
+
+When an authorization exception is raised by the engine, it automatically store the current user's location in a cookie. The called method is `store_location` and is available in your controllers. Then you can use the method `redirect_back_or(default, message = nil)` which either redirects to the stored location if any or redirects the default provided path, with an optional message.

data/lib/adeia/controller_methods.rb

@@ -35,6 +35,11 @@ module Adeia
       return controller_resource.load_records
     end
 
+    def load_records(**args)
+      controller_resource = ControllerResource.new(self, **args)
+      return controller_resource.load_records
+    end
+
     def authorize!(**args)
       ControllerResource.new(self, **args).authorize!
     end
@@ -55,7 +60,7 @@ module Adeia
     end
 
     # Redirect the user to the stored url or the default one provided
-    # 
+    #
     # * *Args*    :
     #   - default path to redirect to
     # * *Returns* :
@@ -66,9 +71,9 @@ module Adeia
     end
 
     # Store the current url in a cookie
-    # 
+    #
     # * *Args*    :
-    # 
+    #
     # * *Returns* :
     #
     def store_location
@@ -77,4 +82,4 @@ module Adeia
 
   end
 
-end
+end

data/lib/adeia/version.rb

@@ -1,3 +1,3 @@
 module Adeia
-  VERSION = "0.10.5"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: adeia
 version: !ruby/object:Gem::Version
-  version: 0.10.5
+  version: 0.11.0
 platform: ruby
 authors:
 - khcr
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-10 00:00:00.000000000 Z
+date: 2016-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails