yousty-activeadmin 1.0.4.pre → 1.0.5.pre

data/docs/13-authorization-adapter.md

@@ -4,68 +4,69 @@ Active Admin offers the ability to define and use your own authorization
 adapter. If implemented, the '#authorized?' will be called when an action is
 taken. By default, '#authorized?' returns true.
 
-
 ## Setting up your own AuthorizationAdapter
 
 Setting up your own `AuthorizationAdapter` is easy! The following example shows
 how to set up and tie your authorization adapter class to Active Admin:
 
-    # app/models/only_authors_authorization.rb
-    class OnlyAuthorsAuthorization < ActiveAdmin::AuthorizationAdapter
-
-        def authorized?(action, subject = nil)
-          case subject
-          when normalized(Post)
-
-            # Only let the author update and delete posts
-            if action == :update || action == :destroy
-              subject.author == user
-
-            # If it's not an update or destroy, anyone can view it
-            else
-              true
-            end
-
-          else
-            true
-          end
-        end
-
+```ruby
+# app/models/only_authors_authorization.rb
+class OnlyAuthorsAuthorization < ActiveAdmin::AuthorizationAdapter
+
+  def authorized?(action, subject = nil)
+    case subject
+    when normalized(Post)
+      # Only let the author update and delete posts
+      if action == :update || action == :destroy
+        subject.author == user
+      else
+        true
+      end
+    else
+      true
     end
+  end
+
+end
+```
 
 In order to hook up `OnlyAuthorsAuthorization` to Active Admin, go to your
 application's `config/initializers/active_admin.rb` and add/modify the line:
 
-    config.authorization_adapter = "OnlyAuthorsAuthorization"
+```ruby
+config.authorization_adapter = "OnlyAuthorsAuthorization"
+```
 
 Authorization adapters can be configured per ActiveAdmin namespace as well, for example:
 
-    ActiveAdmin.setup do |config|
-      config.namespace :admin do |ns|
-        ns.authorization_adapter = "AdminAuthorization"
-      end
-      config.namespace :my do |ns|
-        ns.authorization_adapter = "DashboardAuthorization"
-      end
-    end
+```ruby
+ActiveAdmin.setup do |config|
+  config.namespace :admin do |ns|
+    ns.authorization_adapter = "AdminAuthorization"
+  end
+  config.namespace :my do |ns|
+    ns.authorization_adapter = "DashboardAuthorization"
+  end
+end
+```
 
 Now, whenever a controller action is performed, the `OnlyAuthorsAuthorization`'s
 `#authorized?` method will be called.
 
-
 ## Getting Access to the Current User
 
 From within your authorization adapter, you can call the `#user` method to
 retrieve the current user.
 
-    class OnlyAdmins < ActiveAdmin::AuthorizationAdapter
-
-      def authorized?(action, subject = nil)
-        user.admin?
-      end
+```ruby
+class OnlyAdmins < ActiveAdmin::AuthorizationAdapter
 
-    end
+  def authorized?(action, subject = nil)
+    user.admin?
+  end
 
+end
+```
 
 ## Scoping Collections in Authorization Adapters
 
@@ -73,42 +74,40 @@ retrieve the current user.
 for the adapter to scope the resource's collection. For example, you may want to
 centralize the scoping:
 
-    class OnlyMyAccount < ActiveAdmin::AuthorizationAdapter
+```ruby
+class OnlyMyAccount < ActiveAdmin::AuthorizationAdapter
 
-      def authorized?(action, subject = nil)
-        subject.account == user.account
-      end
+  def authorized?(action, subject = nil)
+    subject.account == user.account
+  end
 
-      def scope_collection(collection)
-        collection.where(:account_id => user.account_id)
-      end
+  def scope_collection(collection, action = Auth::READ)
+    collection.where(account_id: user.account_id)
+  end
 
-    end
+end
+```
 
 All collections presented on Index Screens will be passed through this method
 and will be scoped accordingly.
 
-
 ## Managing Access to Pages
 
 Pages, just like resources, get authorized also. When authorization a page, the
 subject will be an instance of `ActiveAdmin::Page`.
 
-    class OnlyDashboard < ActiveAdmin::AuthorizationAdapter
-      def authorized?(action, subject = nil)
-        case subject
-        when ActiveAdmin::Page
-          if action == :read && subject.name == "Dashboard"
-            true
-          else
-            false
-          end
-        else
-          false
-        end
-      end
+```ruby
+class OnlyDashboard < ActiveAdmin::AuthorizationAdapter
+  def authorized?(action, subject = nil)
+    case subject
+    when ActiveAdmin::Page
+      action == :read && subject.name == "Dashboard" && subject.namespace.name == :admin
+    else
+      false
     end
-
+  end
+end
+```
 
 ## Action Types
 
@@ -133,61 +132,66 @@ authorized to perform an action on a subject.
 
 Simply use the `#authorized?(action, subject) method to check.
 
-    ActiveAdmin.register Post do
-
-      index do
-        column :title
-        column "" do |post|
-          if authorized?(:update, post)
-            link_to("Edit", admin_post_path(post))
-          end
-        end
-
-      end
+```ruby
+ActiveAdmin.register Post do
 
+  index do
+    column :title
+    column '' do |post|
+      link_to 'Edit', admin_post_path(post) if authorized? :update, post
     end
+  end
+
+end
+```
 
 If you are implementing a custom controller action, you can use the
 `#authorize!` method to raise an `ActiveAdmin::AccessDenied` exception.
 
-    ActiveAdmin.register Post do
-
-      member_action :publish, :method => :post do
-        post = Post.find(params[:id])
+```ruby
+ActiveAdmin.register Post do
 
-        authorize! :publish, post
-        post.publish!
+  member_action :publish, method: :post do
+    post = Post.find(params[:id])
 
-        flash[:notice] = "Post has been published"
-        redirect_to [:admin, post]
-      end
+    authorize! :publish, post
+    post.publish!
 
-      action_item :only => :show do
-        if !post.published? && authorized?(:publish, post)
-          link_to("Publish", publish_admin_post_path(post), :method => :post)
-        end
-      end
+    flash[:notice] = "Post has been published"
+    redirect_to [:admin, post]
+  end
 
+  action_item :publish, only: :show do
+    if !post.published? && authorized?(:publish, post)
+      link_to "Publish", publish_admin_post_path(post), method: :post
     end
+  end
 
+end
+```
 
 ## Using the CanCan Adapter
 
 Sub-classing `ActiveAdmin::AuthorizationAdapter` is fairly low level. Many times
 it's nicer to have a simpler DSL for managing authorization. Active Admin
-provides an adapter out of the box for [CanCan](https://github.com/ryanb/cancan).
+provides an adapter out of the box for [CanCan](https://github.com/ryanb/cancan)
+and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
 
 To use the CanCan adapter, simply update the configuration in the Active Admin
 initializer:
 
-    config.authorization_adapter = ActiveAdmin::CanCanAdapter
-    
+```ruby
+config.authorization_adapter = ActiveAdmin::CanCanAdapter
+```
+
 You can also specify a method to be called on unauthorized access. This is necessary
 in order to prevent a redirect loop that can happen if a user tries to access a page
-they don't have permissions for (see [#2081](https://github.com/gregbell/active_admin/issues/2081)).
+they don't have permissions for (see [#2081](https://github.com/activeadmin/activeadmin/issues/2081)).
+
 ```ruby
 config.on_unauthorized_access = :access_denied
-```    
+```
+
 The method `access_denied` would be defined in `application_controller.rb`. Here is one
 example that redirects the user from the page they don't have permission to
 access to a resource they have permission to access (organizations in this case), and
@@ -196,9 +200,9 @@ also displays the error message in the browser:
 ```ruby
 class ApplicationController < ActionController::Base
   protect_from_forgery
-  
+
   def access_denied(exception)
-    redirect_to admin_organizations_path, :alert => exception.message
+    redirect_to admin_organizations_path, alert: exception.message
   end
 end
 ```
@@ -206,22 +210,39 @@ end
 By default this will use the ability class named "Ability". This can also be
 changed from the initializer:
 
-    config.cancan_ability_class = "MyCustomAbility"
+```ruby
+config.cancan_ability_class = "MyCustomAbility"
+```
 
-Now you can simply use CanCan the way that you would expect and Active Admin
-will use it for authorization:
+Now you can simply use CanCan or CanCanCan the way that you would expect and
+Active Admin will use it for authorization:
 
-    # app/models/ability.rb
-    class Ability
-      include CanCan::Ability
+```ruby
+# app/models/ability.rb
+class Ability
+  include CanCan::Ability
+
+  def initialize(user)
+    can :manage, Post
+    can :read, User
+    can :manage, User, id: user.id
+    can :read, ActiveAdmin::Page, name: "Dashboard", namespace_name: :admin
+  end
 
-      def initialize(user)
-        can :manage, Post
-        can :read, User
-        can :manage, User, :id => user.id
-        can :read, ActiveAdmin::Page, :name => "Dashboard"
-      end
+end
+```
 
-    end
+To view more details about the API's, visit project pages of [CanCan](https://github.com/ryanb/cancan) and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
+
+## Using the Pundit Adapter
+
+Active Admin provides an adapter out of the box also for [Pundit](https://github.com/elabs/pundit).
+
+To use the Pundit adapter, simply update the configuration in the Active Admin
+initializer:
+
+```ruby
+config.authorization_adapter = ActiveAdmin::PunditAdapter
+```
 
-To view more details about the CanCan API, visit [https://github.com/ryanb/cancan](https://github.com/ryanb/cancan).
+You can simply use Pundit the way that you would expect and Active Admin will use it for authorization. Check Pundit's documentation to [set up Pundit in your application](https://github.com/elabs/pundit#installation). If you want to use batch actions just ensure that `destroy_all?` method is defined in your policy class. You can use this [template policy](https://github.com/activeadmin/activeadmin/blob/master/spec/support/templates/policies/application_policy.rb) in your application instead of default one generated by Pundit's `rails g pundit:install` command.

data/docs/14-gotchas.md

@@ -0,0 +1,90 @@
+#Gotchas
+
+## Session Commits & Asset Pipeline
+
+When configuring the asset pipeline ensure that the asset prefix 
+(`config.assets.prefix`) is not the same as the namespace of ActiveAdmin 
+(default namespace is `/admin`). If they are the same Sprockets will prevent the 
+session from being committed. Flash messages won't work and you will be unable to 
+use the session for storing anything.
+
+For more information see the following post: 
+[http://www.intridea.com/blog/2013/3/20/rails-assets-prefix-may-disable-your-session](http://www.intridea.com/blog/2013/3/20/rails-assets-prefix-may-disable-your-session)
+
+## Helpers
+
+There are two knowing gotchas with helpers. This hopefully will help you to
+find a solution.
+
+### Helpers are not reloading in development
+
+This is a known and still open [issue](https://github.com/activeadmin/activeadmin/issues/697)
+the only way is to restart your server each time you change a helper.
+
+### Helper maybe not included by default
+
+If you use `config.action_controller.include_all_helpers = false` in your application config, 
+you need to include it by hand.
+
+#### Solutions
+
+##### First use a monkey patch
+
+This works for all ActiveAdmin resources at once.
+
+```ruby
+# config/initializers/active_admin_helpers.rb
+ActiveAdmin::BaseController.class_eval do
+  helper ApplicationHelper
+end
+```
+
+##### Second use the `controller` method
+
+This works only for one resource at a time.
+
+```ruby
+ActiveAdmin.register User do
+  controller do
+    helper UserHelper
+  end
+end
+```
+
+## CSS
+
+In order to avoid the override of your application style (with the Active Admin one), you can properly move the generated file `active_admin.css.scss` from `app/assets/stylesheets` to `vendor/assets/stylesheets`
+
+## Conflicts
+
+### With gems that provides a `search` class method on a model
+
+If a gem defines a `search` class method on a model, this can result in conflicts 
+with the same method provided by `ransack` (a dependency of ActiveAdmin).
+
+Each of this conflicts need to solved is a different way. Some solutions are 
+listed below.
+
+#### `tire`, `retire` and `elasticsearch-rails`
+
+This conflict can be solved, by using explicitly the `search` method of `tire`, 
+`retire` or `elasticsearch-rails`:
+
+##### For `tire` and `retire`
+
+```ruby
+YourModel.tire.search
+```
+
+##### For `elasticsearch-rails`
+
+```ruby
+YourModel.__elasticsearch__.search
+```
+
+### Sunspot Solr
+
+```ruby
+YourModel.solr_search
+```
+

data/docs/2-resource-customization.md

@@ -1,11 +1,11 @@
 # Working with Resources
 
-Every Active Admin resource corresponds to a Rails model. So before creating a 
+Every Active Admin resource corresponds to a Rails model. So before creating a
 resource you must first create a Rails model for it.
 
 ## Create a Resource
 
-The basic command for creating a resource is `rails g active_admin:resource Post`. 
+The basic command for creating a resource is `rails g active_admin:resource Post`.
 The generator will produce an empty `app/admin/post.rb` file like so:
 
 ```ruby
@@ -17,15 +17,66 @@ end
 ## Setting up Strong Parameters
 
 Rails 4 replaces `attr_accessible` with [Strong Parameters](https://github.com/rails/strong_parameters),
-which moves attribute whitelisting from the model to the controller. There are
-talks ([#2594](https://github.com/gregbell/active_admin/issues/2594)) on providing a
-cleaner DSL, but for now you do so like this:
+which moves attribute whitelisting from the model to the controller.
+
+Use the `permit_params` method to define which attributes may be changed:
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params :title, :content, :publisher_id
+end
+```
+
+Any form field that sends multiple values (such as a HABTM association, or an array attribute)
+needs to pass an empty array to `permit_params`:
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params :title, :content, :publisher_id, roles: []
+end
+```
+
+Nested associations in the same form also require an array, but it
+needs to be filled with any attributes used.
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params :title, :content, :publisher_id,
+    tags_attributes: [:id, :name, :description, :_destroy]
+end
+
+# Note that `accepts_nested_attributes_for` is still required:
+class Post < ActiveRecord::Base
+  accepts_nested_attributes_for :tags, allow_destroy: true
+end
+```
+
+If you want to dynamically choose which attributes can be set, pass a block:
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params do
+    params = [:title, :content, :publisher_id]
+    params.push :author_id if current_user.admin?
+    params
+  end
+end
+```
+
+The `permit_params` call creates a method called `permitted_params`. You should use this method when overriding `create` or `update` actions:
 
 ```ruby
 ActiveAdmin.register Post do
   controller do
-    def permitted_params
-      params.permit post: [:title, :content, :author]
+    def create
+      # Good
+      @post = Post.new(permitted_params[:post])
+      # Bad
+      @post = Post.new(params[:post])
+
+      if @post.save
+        # ...
+      end
     end
   end
 end
@@ -53,9 +104,6 @@ ActiveAdmin.register Post, as: "Article"
 
 The resource will then be available at `/admin/articles`.
 
-This will also change the key of the resource params passed to the controller.
-In Rails 4, the `permitted_params` key will need to be changed from `:post` to `:article`.
-
 ## Customize the Namespace
 
 We use the `admin` namespace by default, but you can use anything:
@@ -172,7 +220,7 @@ name? Well, you have to refer to it by its `:id`.
 
 ```ruby
 # config/initializers/active_admin.rb
-config.namespace :admin do |admin
+config.namespace :admin do |admin|
   admin.build_menu do |menu|
     menu.add id: 'blog', label: proc{"Something dynamic"}, priority: 0
   end
@@ -235,15 +283,25 @@ ActiveAdmin.register Post do
 end
 ```
 
-## Customizing resource retrieval
+## Eager loading
 
 A common way to increase page performance is to elimate N+1 queries by eager loading associations:
 
+```ruby
+ActiveAdmin.register Post do
+  includes :author, :categories
+end
+```
+
+## Customizing resource retrieval
+
+If you need to customize the collection properties, you can overwrite the `scoped_collection` method.
+
 ```ruby
 ActiveAdmin.register Post do
   controller do
     def scoped_collection
-      super.includes :author, :categories
+      end_of_association_chain.where(visibility: true)
     end
   end
 end
@@ -255,7 +313,7 @@ If you need to completely replace the record retrieving code (e.g., you have a c
 ```ruby
 ActiveAdmin.register Post do
   controller do
-    def resource
+    def find_resource
       Post.where(id: params[:id]).first!
     end
   end
@@ -332,9 +390,18 @@ different menus, say perhaps based on user permissions. For example:
 
 ```ruby
 ActiveAdmin.register Ticket do
-  belongs_to: :project
+  belongs_to :project
   navigation_menu do
     authorized?(:manage, SomeResource) ? :project : :restricted_menu
   end
 end
 ```
+
+If you still want your `belongs_to` resources to be available in the default menu
+and through non-nested routes, you can use the `:optional` option. For example:
+
+```ruby
+ActiveAdmin.register Ticket do
+  belongs_to :project, optional: true
+end
+```