activeadmin-orac 1.0.0.pre4

data/docs/11-decorators.md

@@ -0,0 +1,55 @@
+# 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.register Post do
+  decorate_with PostDecorator
+
+  index do
+    column :title
+    column :image
+    actions
+  end
+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 block.
+
+```ruby
+ActiveAdmin.register Post do
+  decorate_with PostDecorator
+
+  form decorate: true do |f|
+    # ...
+  end
+end
+```

data/docs/12-arbre-components.md

@@ -0,0 +1,150 @@
+# Arbre Components
+
+Arbre 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 Arbre components or resource
+controller functions.
+
+```ruby
+ActiveAdmin.register Post do
+  show do
+    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
+  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
+show do
+  panel "Post Details" do
+    render partial: "details", locals: {post: post}
+  end
+
+  panel "Post Tags" do
+    render partial: "tags",    locals: {post: post}
+  end
+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.
+
+## 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.
+
+## 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", a type, which defaults to nil, 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', :ok
+# => <span class='status_tag active ok'>Active</span>
+
+status_tag 'active', :ok, class: 'important', id: 'status_123', label: 'on'
+# => <span class='status_tag active ok important' id='status_123'>on</span>
+```

data/docs/13-authorization-adapter.md

@@ -0,0 +1,248 @@
+# 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
+
+Setting up your own `AuthorizationAdapter` is easy! 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.
+
+Simply 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, simply 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.