activeadmin-rails 1.7.0

data/docs/10-custom-pages.md

@@ -0,0 +1,148 @@
+---
+layout: default
+nav_order: 10
+title: Custom Pages
+redirect_from: /docs/10-custom-pages.html
+---
+
+# Custom Pages
+
+If you have data you want on a standalone page that isn't tied to a resource,
+custom pages provide you with a familiar syntax and feature set:
+
+* a menu item
+* sidebars
+* action items
+* page actions
+
+## Create a new Page
+
+Creating a page is as simple as calling `register_page`:
+
+```ruby
+# app/admin/calendar.rb
+ActiveAdmin.register_page "Calendar" do
+end
+```
+
+and defining a partial:
+
+```ruby
+# app/views/admin/calendar/_calendar.html.arb
+table do
+  thead do
+    tr do
+      %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].each &method(:th)
+    end
+  end
+  tbody do
+    # ...
+  end
+end
+```
+
+## Customize the Menu
+
+See the [Menu](2-resource-customization.md#customize-the-menu) documentation.
+
+## Customize the breadcrumbs
+
+```ruby
+ActiveAdmin.register_page "Calendar" do
+  breadcrumb do
+    ['admin', 'calendar']
+  end
+end
+```
+
+## Customize the Namespace
+
+We use the `admin` namespace by default, but you can use anything:
+
+```ruby
+# Available at /today/calendar
+ActiveAdmin.register_page "Calendar", namespace: :today
+
+# Available at /calendar
+ActiveAdmin.register_page "Calendar", namespace: false
+```
+
+## Belongs To
+
+To nest the page within another resource, you can use the `belongs_to` method:
+
+```ruby
+ActiveAdmin.configure_resource Project
+ActiveAdmin.register_page "Status" do
+  config.belongs_to :project
+end
+```
+
+See also the [Belongs To](2-resource-customization.md#belongs-to) documentation
+and examples.
+
+## Add a Sidebar
+
+See the [Sidebars](7-sidebars.md) documentation.
+
+## Add an Action Link
+
+Just like other resources, you can add action links.
+
+```ruby
+# app/views/admin/calendar/action_item.html.arb
+div(class: :action_items) do
+  ...
+  action_link "View Site", "/"
+end
+```
+
+## Add a Page Action
+
+Page actions are custom controller actions (which mirror the resource DSL for
+the same feature).
+
+```ruby
+# admin/calendar.rb
+# Defines the route `/admin/calendar/add_event` which can handle HTTP POST requests.
+config.add_page_route :add_event, method: :post
+
+# app/controllers/admin/calendar_controller
+class Admin::CalendarController < ActiveAdmin::PageController
+  def add_event
+    # ...
+    redirect_to admin_calendar_path, notice: "Your event was added"
+  end
+end
+
+# app/views/admin/calendar/action_item.html.arb
+div(class: :action_items) do
+  ...
+  action_link "Add Event", admin_calendar_add_event_path, method: :post
+end
+```
+
+Clicking on the action item will reload page and display the message "Your event
+was added"
+
+Page actions can handle multiple HTTP verbs.
+
+```ruby
+config.add_page_route :add_event, method: [:get, :post] do
+  # ...
+end
+```
+
+See also the [Custom Actions](8-custom-actions.md#http-verbs) example.
+
+## Use custom column as id
+
+You can use custom parameter instead of id
+
+```ruby
+class Admin::User < ActiveAdmin::ResourceController
+  defaults finder: :find_by_name
+end
+```
+
+This defines the resource route as `/admin/users/john` if user name is john

data/docs/11-decorators.md

@@ -0,0 +1,66 @@
+---
+layout: default
+nav_order: 11
+title: Decorators
+redirect_from: /docs/11-decorators.html
+---
+
+# Decorators
+
+Active Admin allows you to use the decorator pattern to provide view-specific
+versions of a resource. [Draper](https://github.com/drapergem/draper) is
+recommended but not required.
+
+To use decorator support without Draper, your decorator must support a variety
+of collection methods to support pagination, filtering, etc. See
+[this github issue discussion](https://github.com/activeadmin/activeadmin/issues/3600)
+and [this gem](https://github.com/kiote/activeadmin-poro-decorator) for more details.
+
+## Example usage
+
+```ruby
+# app/models/post.rb
+class Post < ActiveRecord::Base
+  # has title, content, and image_url
+end
+
+# app/decorators/post_decorator.rb
+class PostDecorator < Draper::Decorator
+  delegate_all
+
+  def image
+    h.image_tag model.image_url
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.configure_resource Post do |config|
+  config.decorator_class_name = "PostDecorator"
+end
+
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  column :title
+  column :image
+  actions
+end
+```
+
+## Forms
+
+By default, ActiveAdmin does *not* decorate the resource used to render forms.
+If you need ActiveAdmin to decorate the forms, you can pass `decorate: true` to the
+form page presenter.
+
+```ruby
+ActiveAdmin.configure_resource Post do |config|
+  config.decorator_class_name = "PostDecorator"
+
+  config.set_page_options :form, decorate: true
+end
+
+# app/views/admin/posts/_form.html.arb
+active_admin_form_for(resource) do |f|
+  # ...
+end
+```

data/docs/12-arbo-components.md

@@ -0,0 +1,200 @@
+---
+layout: default
+nav_order: 12
+title: Arbo Components
+redirect_from: /docs/12-arbo-components.html
+---
+
+# Arbo Components
+
+Arbo allows the creation of shareable and extendable HTML components and is
+used throughout Active Admin to create view components.
+
+## Text Node
+
+Sometimes it makes sense to insert something into a registered resource like a
+non-breaking space or some text. The text_node method can be used to insert
+these elements into the page inside of other Arbo components or resource
+controller functions.
+
+```ruby
+panel "Post Details" do
+  attributes_table_for post do
+    row :id
+    row 'Tags' do
+      post.tags.each do |tag|
+        a tag, href: admin_post_path(q: {tagged_with_contains: tag})
+        text_node " ".html_safe
+      end
+    end
+  end
+end
+```
+
+## Panels
+
+A panel is a component that takes up all available horizontal space and takes a
+title and a hash of attributes as arguments. If a sidebar is present, a panel
+will take up the remaining space.
+
+This will create two stacked panels:
+
+```ruby
+panel "Post Details" do
+  render partial: "details", locals: {post: post}
+end
+
+panel "Post Tags" do
+  render partial: "tags",    locals: {post: post}
+end
+```
+
+## Columns
+
+The Columns component allows you draw content into scalable columns. All you
+need to do is define the number of columns and the component will take care of
+the rest.
+
+### Simple Columns
+
+To create simple columns, use the `columns` method. Within the block, call
+the #column method to create a new column.
+
+```ruby
+columns do
+  column do
+    span "Column #1"
+  end
+
+  column do
+    span "Column #2"
+  end
+end
+```
+
+### Spanning Multiple Columns
+
+To create columns that have multiple spans, pass the :span option to the column
+method.
+
+```ruby
+columns do
+  column span: 2 do
+    span "Column # 1"
+  end
+  column do
+    span "Column # 2"
+  end
+end
+```
+
+By default, each column spans 1 column. The above layout would have 2 columns,
+the first being twice as large as the second.
+
+### Custom Column Widths
+
+Active Admin uses a fluid width layout, causing column width to be defined
+using percentages. Due to using this style of layout, columns can shrink or
+expand past points that may not be desirable. To overcome this issue,
+columns provide `:max_width` and `:min_width` options.
+
+```ruby
+columns do
+  column max_width: "200px", min_width: "100px" do
+    span "Column # 1"
+  end
+  column do
+    span "Column # 2"
+  end
+end
+```
+
+In the above example, the first column will not grow larger than 200px and will
+not shrink less than 100px.
+
+
+### Custom Column Class
+
+Pass the `:class` option to the column method to set a custom class.
+
+```ruby
+columns do
+  column class: "important" do
+    span "Column # 1"
+  end
+  column do
+    span "Column # 2"
+  end
+end
+```
+
+
+## Table For
+
+Table For provides the ability to create tables like those present
+in `index_as_table`. It takes a collection and a hash of options and then
+uses `column` to build the fields to show with the table.
+
+```ruby
+table_for order.payments do
+  column(:payment_type) { |payment| payment.payment_type.titleize }
+  column "Received On",     :created_at
+  column "Details & Notes", :payment_details
+  column "Amount",          :amount_in_dollars
+end
+```
+
+The `column` method can take a title as its first argument and data
+(`:your_method`) as its second (or first if no title provided). Column also
+takes a block.
+
+### Internationalization
+
+To customize the internationalization for the component, specify a resource to
+use for translations via the `i18n` named parameter. This is only necessary for
+non-`ActiveRecord::Relation` collections:
+
+```ruby
+table_for payments, i18n: Payment do
+  # ...
+end
+```
+
+## Status tag
+
+Status tags provide convenient syntactic sugar for styling items that have
+status. A common example of where the status tag could be useful is for orders
+that are complete or in progress. `status_tag` takes a status, like
+"In Progress", and a hash of options. The status_tag will generate HTML markup
+that Active Admin CSS uses in styling.
+
+```ruby
+status_tag 'In Progress'
+# => <span class='status_tag in_progress'>In Progress</span>
+
+status_tag 'active', class: 'important', id: 'status_123', label: 'on'
+# => <span class='status_tag active important' id='status_123'>on</span>
+```
+
+## Tabs
+
+The Tabs component is helpful for saving page real estate. The first tab will be
+the one open when the page initially loads and the rest hidden. You can click
+each tab to toggle back and forth between them. Arbo supports unlimited number
+of tabs.
+
+```ruby
+tabs do
+  tab :active do
+    table_for orders.active do
+      ...
+    end
+  end
+
+  tab :inactive do
+    table_for orders.inactive do
+      ...
+    end
+  end
+end
+```

data/docs/13-authorization-adapter.md

@@ -0,0 +1,288 @@
+---
+layout: default
+nav_order: 13
+title: Authorization Adapter
+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"
+```
+
+Now, whenever a controller action is performed, the `OnlyAuthorsAuthorization`'s
+`#authorized?` method will be called.
+
+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
+```
+
+## 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
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  column :title
+  column '' do |post|
+    link_to 'Edit', admin_post_path(post) if authorized? :update, post
+  end
+end
+```
+
+If you are implementing a custom controller action, you can use the
+`#authorize!` method to raise an `ActiveAdmin::AccessDenied` exception.
+
+```ruby
+class Admin::Post < ActiveAdmin::ResourceController
+
+  def publish
+    post = Post.find(params[:id])
+
+    authorize! :publish, post
+    post.publish!
+
+    flash[:notice] = "Post has been published"
+    redirect_to [:admin, post]
+  end
+end
+
+# app/views/admin/posts/_action_item.html.arb
+div(class: :action_items) do
+  if params[:action] == 'show'
+    if !post.published? && authorized?(:publish, post)
+      action_link :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 also provides an adapter out of the box for
+[Pundit](https://github.com/elabs/pundit).
+
+To use the Pundit adapter, update the configuration in the Active Admin
+initializer:
+
+```ruby
+config.authorization_adapter = ActiveAdmin::PunditAdapter
+```
+
+Once that's done, Active Admin will pick up your Pundit policies, and use
+them for authorization. For more information about setting up Pundit, see
+[their documention](https://github.com/elabs/pundit#installation).
+
+Pundit also has [verify_authorized and/or verify_policy_scoped
+methods](https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used)
+to enforce usage of `authorized` and `policy_scope`. This conflicts with Active
+Admin's authorization architecture, so if you're using those features, you'll
+want to disable them for Active Admin's controllers:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Pundit
+  after_action :verify_authorized, except: :index, unless: :active_admin_controller?
+  after_action :verify_policy_scoped, only: :index, unless: :active_admin_controller?
+
+  def active_admin_controller?
+    is_a?(ActiveAdmin::BaseController)
+  end
+end
+```
+
+If you want to use batch actions, ensure that `destroy_all?` method is defined
+in your policy class. You can use this [template
+policy](https://github.com/varyonic/activeadmin/blob/main/spec/support/templates/policies/application_policy.rb)
+in your application instead of default one generated by Pundit's
+`rails g pundit:install` command.
+