activeadmin_addons 1.1.2 → 1.2.0

data/vendor/bundle/ruby/2.3.0/bundler/gems/activeadmin-f71b375325eb/docs/13-authorization-adapter.md

@@ -0,0 +1,266 @@
+---
+redirect_from: /docs/13-authorization-adapter.html
+---
+
+# Authorization Adapter
+
+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
+
+The following example shows how to set up and tie your authorization
+adapter class to Active Admin:
+
+```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:
+
+```ruby
+config.authorization_adapter = "OnlyAuthorsAuthorization"
+```
+
+Authorization adapters can be configured per ActiveAdmin namespace as well, for
+example:
+
+```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.
+
+```ruby
+class OnlyAdmins < ActiveAdmin::AuthorizationAdapter
+
+  def authorized?(action, subject = nil)
+    user.admin?
+  end
+
+end
+```
+
+## Scoping Collections in Authorization Adapters
+
+`ActiveAdmin::AuthorizationAdapter` also provides a hook method
+(`#scope_collection`) for the adapter to scope the resource's collection. For
+example, you may want to centralize the scoping:
+
+```ruby
+class OnlyMyAccount < ActiveAdmin::AuthorizationAdapter
+
+  def authorized?(action, subject = nil)
+    subject.account == user.account
+  end
+
+  def scope_collection(collection, action = Auth::READ)
+    collection.where(account_id: user.account_id)
+  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 too. When authorizing a page, the
+subject will be an instance of `ActiveAdmin::Page`.
+
+```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
+
+By default Active Admin simplifies the controller actions into 4 actions:
+
+* `:read` - This controls if the user can view the menu item as well as the
+  index and show screens.
+* `:create` - This controls if the user can view the new screen and submit
+  the form to the create action.
+* `:update` - This controls if the user can view the edit screen and submit
+  the form to the update action.
+* `:destroy` - This controls if the user can delete a resource.
+
+Each of these actions is available as a constant. Eg: `:read` is available as
+`ActiveAdmin::Authorization::READ`.
+
+## Checking for Authorization in Controllers and Views
+
+Active Admin provides a helper method to check if the current user is
+authorized to perform an action on a subject.
+
+Use the `#authorized?(action, subject)` method to check.
+
+```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.
+
+```ruby
+ActiveAdmin.register Post do
+
+  member_action :publish, method: :post do
+    post = Post.find(params[:id])
+
+    authorize! :publish, post
+    post.publish!
+
+    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)
+and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
+
+To use the CanCan adapter, update the configuration in the Active Admin
+initializer:
+
+```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/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 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
+  end
+end
+```
+
+By default this will use the ability class named "Ability". This can also be
+changed from the initializer:
+
+```ruby
+config.cancan_ability_class = "MyCustomAbility"
+```
+
+Now you can simply use CanCan or CanCanCan the way that you would expect and
+Active Admin will use it for authorization:
+
+```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
+
+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
+```
+
+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/vendor/bundle/ruby/2.3.0/bundler/gems/activeadmin-f71b375325eb/docs/14-gotchas.md

@@ -0,0 +1,138 @@
+---
+redirect_from: /docs/14-gotchas.html
+---
+
+# Gotchas
+
+## Security
+
+### Spreadsheet applications vulnerable to unescaped CSV data
+
+If your CSV export includes untrusted data provided by your users, it's possible
+that they could include an executable formula that could call arbitrary commands
+on your computer. See
+[#4256](https://github.com/activeadmin/activeadmin/issues/4256) for more
+details.
+
+## 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).
+
+## Helpers
+
+There are two known 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 do one of these things:
+
+* You can properly move the generated file `active_admin.scss` from
+  `app/assets/stylesheets` to `vendor/assets/stylesheets`.
+* You can remove all `require_tree` commands from your root level css files,
+  where the `active_admin.scss` is in the tree.
+
+## 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
+```
+
+### Rails 5 scaffold generators
+
+Active Admin requires the `inherited_resources` gem which may break scaffolding
+under Rails 5 as it replaces the default scaffold generator. The solution is to
+configure the default controller in `config/application.rb` as outlined in
+[activeadmin/inherited_resources#195](https://github.com/activeadmin/inherited_resources/issues/195)
+
+```ruby
+module SampleApp
+  class Application < Rails::Application
+    ...
+    config.app_generators.scaffold_controller = :scaffold_controller
+    ...
+  end
+end
+```
+
+## Authentication & Application Controller
+
+The `ActiveAdmin::BaseController` inherits from the `ApplicationController`. Any
+authentication method(s) specified in the `ApplicationController` callbacks will
+be called instead of the authentication method in the active admin config file.
+For example, if the ApplicationController has a callback `before_action
+:custom_authentication_method` and the config file's authentication method is
+`config.authentication_method = :authenticate_active_admin_user`, then
+`custom_authentication_method` will be called instead of
+`authenticate_active_admin_user`.

data/vendor/bundle/ruby/2.3.0/bundler/gems/activeadmin-f71b375325eb/docs/2-resource-customization.md

@@ -0,0 +1,466 @@
+---
+redirect_from: /docs/2-resource-customization.html
+---
+
+# Working with Resources
+
+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 generator will produce an empty `app/admin/posts.rb` file like so:
+
+```ruby
+ActiveAdmin.register Post do
+  # everything happens here :D
+end
+```
+
+## Setting up Strong Parameters
+
+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`:
+
+If your HABTM is `roles`, you should permit `role_ids: []`
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params :title, :content, :publisher_id, role_ids: []
+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
+```
+
+If your resource is nested, declare `permit_params` after `belongs_to`:
+
+```ruby
+ActiveAdmin.register Post do
+  belongs_to :user
+  permit_params :title, :content, :publisher_id
+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 create
+      # Good
+      @post = Post.new(permitted_params[:post])
+      # Bad
+      @post = Post.new(params[:post])
+
+      if @post.save
+        # ...
+      end
+    end
+  end
+end
+```
+
+## Disabling Actions on a Resource
+
+All CRUD actions are enabled by default. These can be disabled for a given resource:
+
+```ruby
+ActiveAdmin.register Post do
+  actions :all, except: [:update, :destroy]
+end
+```
+
+## Renaming Action Items
+
+You can use translations to override labels and page titles for actions such as
+new, edit, and destroy by providing a resource specific translation.  For
+example, to change 'New Offer' to 'Make an Offer' add the following in
+config/locales/[en].yml:
+
+```yaml
+en:
+  active_admin:
+    resources:
+      offer: # Registered resource
+        new_model: 'Make an Offer' # new action item
+        edit_model: 'Change Offer' # edit action item
+        delete_model: 'Cancel Offer' # delete action item
+```
+
+See the [default en.yml](/config/locales/en.yml) locale file for
+existing translations and examples.
+
+## Rename the Resource
+
+By default, any references to the resource (menu, routes, buttons, etc) in the
+interface will use the name of the class. You can rename the resource by using
+the `:as` option.
+
+```ruby
+ActiveAdmin.register Post, as: "Article"
+```
+
+The resource will then be available at `/admin/articles`.
+
+## Customize the Namespace
+
+We use the `admin` namespace by default, but you can use anything:
+
+```ruby
+# Available at /today/posts
+ActiveAdmin.register Post, namespace: :today
+
+# Available at /posts
+ActiveAdmin.register Post, namespace: false
+```
+
+## Customize the Menu
+
+The resource will be displayed in the global navigation by default. To disable
+the resource from being displayed in the global navigation:
+
+```ruby
+ActiveAdmin.register Post do
+  menu false
+end
+```
+
+The menu method accepts a hash with the following options:
+
+* `:label` - The string or proc label to display in the menu. If it's a proc, it
+  will be called each time the menu is rendered.
+* `:parent` - The string id (or label) of the parent used for this menu
+* `:if` - A block or a symbol of a method to call to decide if the menu item
+  should be displayed
+* `:priority` - The integer value of the priority, which defaults to `10`
+
+### Labels
+
+To change the name of the label in the menu:
+
+```ruby
+ActiveAdmin.register Post do
+  menu label: "My Posts"
+end
+```
+
+If you want something more dynamic, pass a proc instead:
+
+```ruby
+ActiveAdmin.register Post do
+  menu label: proc{ I18n.t "mypost" }
+end
+```
+
+### Menu Priority
+
+Menu items are sorted first by their numeric priority, then alphabetically. Since
+every menu by default has a priority of `10`, the menu is normally alphabetical.
+
+You can easily customize this:
+
+```ruby
+ActiveAdmin.register Post do
+  menu priority: 1 # so it's on the very left
+end
+```
+
+### Conditionally Showing / Hiding Menu Items
+
+Menu items can be shown or hidden at runtime using the `:if` option.
+
+```ruby
+ActiveAdmin.register Post do
+  menu if: proc{ current_user.can_edit_posts? }
+end
+```
+
+The proc will be called in the context of the view, so you have access to all
+your helpers and current user session information.
+
+### Drop Down Menus
+
+In many cases, a single level navigation will not be enough to manage a large
+application. In that case, you can group your menu items under a parent menu item.
+
+```ruby
+ActiveAdmin.register Post do
+  menu parent: "Blog"
+end
+```
+
+Note that the "Blog" parent menu item doesn't even have to exist yet; it can be
+dynamically generated for you.
+
+### Customizing Parent Menu Items
+
+All of the options given to a standard menu item are also available to
+parent menu items. In the case of complex parent menu items, you should
+configure them in the Active Admin initializer.
+
+```ruby
+# config/initializers/active_admin.rb
+config.namespace :admin do |admin|
+  admin.build_menu do |menu|
+    menu.add label: 'Blog', priority: 0
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  menu parent: 'Blog'
+end
+```
+
+### Dynamic Parent Menu Items
+
+While the above works fine, what if you want a parent menu item with a dynamic
+name? Well, you have to refer to it by its `:id`.
+
+```ruby
+# config/initializers/active_admin.rb
+config.namespace :admin do |admin|
+  admin.build_menu do |menu|
+    menu.add id: 'blog', label: proc{"Something dynamic"}, priority: 0
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  menu parent: 'blog'
+end
+```
+
+### Adding Custom Menu Items
+
+Sometimes it's not enough to just customize the menu label. In this case, you
+can customize the menu for the namespace within the Active Admin initializer.
+
+```ruby
+# config/initializers/active_admin.rb
+config.namespace :admin do |admin|
+  admin.build_menu do |menu|
+    menu.add label: "The Application", url: "/", priority: 0
+
+    menu.add label: "Sites" do |sites|
+      sites.add label: "Google",
+                url: "http://google.com",
+                html_options: { target: :blank }
+
+      sites.add label: "Facebook",
+                url: "http://facebook.com"
+
+      sites.add label: "Github",
+                url: "http://github.com"
+    end
+  end
+end
+```
+
+This will be registered on application start before your resources are loaded.
+
+## Scoping the queries
+
+If your administrators have different access levels, you may sometimes want to
+scope what they have access to. Assuming your User model has the proper
+has_many relationships, you can simply scope the listings and finders like so:
+
+```ruby
+ActiveAdmin.register Post do
+  scope_to :current_user # limits the accessible posts to `current_user.posts`
+
+  # Or if the association doesn't have the default name:
+  scope_to :current_user, association_method: :blog_posts
+
+  # Finally, you can pass a block to be called:
+  scope_to do
+    User.most_popular_posts
+  end
+end
+```
+
+You can also conditionally apply the scope:
+
+```ruby
+ActiveAdmin.register Post do
+  scope_to :current_user, if:     proc{ current_user.limited_access? }
+  scope_to :current_user, unless: proc{ current_user.admin? }
+end
+```
+
+## Eager loading
+
+A common way to increase page performance is to eliminate N+1 queries by eager
+loading associations:
+
+```ruby
+ActiveAdmin.register Post do
+  includes :author, :categories
+end
+```
+
+## Customizing resource retrieval
+
+Our controllers are built on [Inherited
+Resources](https://github.com/activeadmin/inherited_resources), so you can use
+[all of its
+features](https://github.com/activeadmin/inherited_resources#overwriting-defaults).
+
+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
+      end_of_association_chain.where(visibility: true)
+    end
+  end
+end
+```
+
+If you need to completely replace the record retrieving code (e.g., you have a
+custom `to_param` implementation in your models), override the `resource` method
+on the controller:
+
+```ruby
+ActiveAdmin.register Post do
+  controller do
+    def find_resource
+      scoped_collection.where(id: params[:id]).first!
+    end
+  end
+end
+```
+
+Note that if you use an authorization library like CanCan, you should be careful
+to not write code like this, otherwise **your authorization rules won't be
+applied**:
+
+```ruby
+ActiveAdmin.register Post do
+  controller do
+    def find_resource
+      Post.where(id: params[:id]).first!
+    end
+  end
+end
+```
+
+## Belongs To
+
+It's common to want to scope a series of resources to a relationship. For
+example a Project may have many Milestones and Tickets. To nest the resource
+within another, you can use the `belongs_to` method:
+
+```ruby
+ActiveAdmin.register Project
+ActiveAdmin.register Ticket do
+  belongs_to :project
+end
+```
+
+Projects will be available as usual and tickets will be available by visiting
+`/admin/projects/1/tickets` assuming that a Project with the id of 1 exists.
+Active Admin does not add "Tickets" to the global navigation because the routes
+can only be generated when there is a project id.
+
+To create links to the resource, you can add them to a sidebar (one of the many
+possibilities for how you may with to handle your user interface):
+
+```ruby
+ActiveAdmin.register Project do
+
+  sidebar "Project Details", only: [:show, :edit] do
+    ul do
+      li link_to "Tickets",    admin_project_tickets_path(resource)
+      li link_to "Milestones", admin_project_milestones_path(resource)
+    end
+  end
+end
+
+ActiveAdmin.register Ticket do
+  belongs_to :project
+end
+
+ActiveAdmin.register Milestone do
+  belongs_to :project
+end
+```
+
+In some cases (like Projects), there are many sub resources and you would
+actually like the global navigation to switch when the user navigates "into" a
+project. To accomplish this, Active Admin stores the `belongs_to` resources in a
+separate menu which you can use if you so wish. To use:
+
+```ruby
+ActiveAdmin.register Ticket do
+  belongs_to :project
+  navigation_menu :project
+end
+
+ActiveAdmin.register Milestone do
+  belongs_to :project
+  navigation_menu :project
+end
+```
+
+Now, when you navigate to the tickets section, the global navigation will
+only display "Tickets" and "Milestones". When you navigate back to a
+non-belongs_to resource, it will switch back to the default menu.
+
+You can also defer the menu lookup until runtime so that you can dynamically show
+different menus, say perhaps based on user permissions. For example:
+
+```ruby
+ActiveAdmin.register Ticket do
+  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
+```