Merge pull request #149 from basemate/update_integration_docs

Update integration docs

Author: jonasjabari

docs/integrations/README.md

@@ -4,8 +4,7 @@
 
 1. [ActionCable](/docs/integrations/websockets.md)
 
-## Auth
+## Authentication and Authorization
 
-2. Devise (coming soon)
-3. Pundit (coming soon)
-4. CanCanCan (coming soon)
+2. [Devise](/docs/integrations/devise.md)
+3. [Pundit or CanCanCan](/docs/integrations/pundit_or_cancancan.md)

docs/integrations/devise.md

@@ -0,0 +1,27 @@
+# Authentication via Devise
+
+We recommend using a proven authentication solution like Devise for your Rails app. Find out more about Devise [here](https://github.com/plataformatec/devise/).
+
+## Setting up Devise with your existing matestack application
+
+Just follow the [Devise installation guide](https://github.com/plataformatec/devise/#getting-started) and add it to the models and controller actions you want.
+
+## Adding matestack to a Rails app that already uses Devise
+
+As Devise mainly lives in your models and controllers while matestack is meant to replace your view layer, there shouldn't be much to change for you. Just make sure to trigger the right `before_action`s when adding matestack's `responder_for` to a controller action!
+
+
+## Example
+
+This is just your average Rails user controller. The `before_action` gets called on initial pageload and on every subsequent AJAX request the client sends.
+
+```ruby
+class UserController < ApplicationController
+  before_action :authenticate_user! # Devise authentication
+
+  def show
+    responder_for(Pages::UserApp::ShowPage) # matestack page responder
+  end
+
+end
+```

docs/integrations/pundit_or_cancancan.md

@@ -0,0 +1,72 @@
+# Authorization via Pundit or CanCanCan
+
+At [basemate](https://basemate.io), we have had good experiences using matestack with [Pundit](https://github.com/varvet/pundit). [CanCanCan](https://github.com/CanCanCommunity/cancancan), another very popular authorization library in Rails, is also supported, as shown below!
+
+Both Pundit and CanCanCan use pure Ruby and focus on the model and controller layer, so they are compatible to matestack's UI library.
+
+## Example 1: Pundit
+
+Here we see how Pundit defines policies and we can check for them in the controller action, just before matestack's `responder_for`!
+
+
+A Pundit example in `app/policies/user_policy.rb`:
+```ruby
+class UserPolicy
+  attr_reader :user
+
+  def initialize(user)
+    @user = user
+  end
+
+  def show?
+    user.is_visible?
+  end
+
+end
+```
+
+Matestack's `app/controllers/user_controller.rb`:
+
+```ruby
+class UserController < ApplicationController
+
+  def show
+    @user = User.find_by(id: params[:id])
+    authorize @user # checking Pundit policy
+    responder_for(Pages::UserApp::ShowPage) # matestack page responder
+  end
+
+end
+```
+
+## Example 2: CanCanCan
+
+Here we see how CanCanCan defines abilities and we can check for them in the controller action, just before matestack's `responder_for`!
+
+
+CanCanCan's `app/models/ability.rb` example, borrowed from their guides:
+```ruby
+class Ability
+  include CanCan::Ability
+
+  def initialize(user)
+    can :read, :all # permissions for every user, even if not logged in    
+    # [...]
+  end
+
+end
+```
+
+Matestack's `app/controllers/user_controller.rb`:
+
+```ruby
+class UserController < ApplicationController
+
+  def show
+    @user = User.find_by(id: params[:id])
+    authorize! :read, @user # checking for CanCanCan ability
+    responder_for(Pages::UserApp::ShowPage) # matestack page responder
+  end
+
+end
+```

docs/integrations/websockets.md

@@ -1,9 +1,9 @@
 # Websockets
 
-Websockets can easily be integrated into matestack. matestack uses Rails ActionCable
+Websockets can easily be integrated into matestack. Matestack uses Rails ActionCable
 for this feature.
 
-## Creata a Channel on the serverside
+## Create a Channel on the serverside
 
 `app/channels/matestack_ui_core_channel.rb`
 
@@ -17,7 +17,7 @@ class MatestackUiCoreChannel < ApplicationCable::Channel
 end
 ```
 
-## Add a Subscription on the clientside and link to matestack event hub
+## Add a Subscription on the client side and link to matestack event hub
 
 `app/assets/javascripts/application.js`