activeadmin 0.5.1 → 0.6.0

data/docs/12-arbre-components.md

@@ -142,4 +142,4 @@ status_tag will generate html markup that Active Admin css uses in styling.
       :id => 'status_123', 
       :label => 'on'
     )
-    # => <span class='status_tag active ok important' id='status_123'>on</span>
+    # => <span class='status_tag active ok important' id='status_123'>on</span>

data/docs/13-authorization-adapter.md

@@ -0,0 +1,206 @@
+# 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:
+
+    # app/models/only_authors_authorization.rb
+    class OnlyAuthorsAuthorization < ActiveAdmin::AuthorizationAdapter
+
+        def authorized?(action, subject = nil)
+          case subject
+          when normalize(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
+
+    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"
+
+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
+
+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
+
+    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:
+
+    class OnlyMyAccount < ActiveAdmin::AuthorizationAdapter
+
+      def authorized?(action, subject = nil)
+        subject.account == user.account
+      end
+
+      def scope_collection(collection)
+        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 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
+    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.
+
+    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
+
+    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])
+
+        authorize! :publish, post
+        post.publish!
+
+        flash[:notice] = "Post has been published"
+        redirect_to [:admin, post]
+      end
+
+      action_item :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).
+
+To use the CanCan adapter, simply update the configuration in the Active Admin
+initializer:
+
+    config.authorization_adapter = ActiveAdmin::CanCanAdapter
+
+By default this will use the ability class named "Ability". This can also be
+changed from the initializer:
+
+    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:
+
+    # app/models/ability.rb
+    class Ability
+      include CanCan::Ability
+
+      def intialize(user)
+        can :manage, Post
+        can :read, User
+        can :manage, User, :id => user.id
+        can :read, ActiveAdmin::Page, :name => "Dashboard"
+      end
+
+    end
+
+To view more details about the CanCan API, visit [https://github.com/ryanb/cancan](https://github.com/ryanb/cancan).

data/docs/2-resource-customization.md

@@ -59,6 +59,31 @@ instead of a string. The proc will be called each time the menu is rendered.
       menu :label => proc{ I18n.t("mypost") }
     end
 
+### Menu Priority
+
+By default Active Admin sorts menus alphabetically. Some times you want specific
+resources to show up at the beginning or the end of your menu.
+
+Each menu item is given an integer priority value (default 10). You can set it
+to edit the location of the menu item.
+
+    ActiveAdmin.register Post do
+      menu :priority => 1
+    end
+
+This would ensure that the Post menu item, is at the beginning of the menu.
+
+### Conditionally Showing / Hiding Menu Items
+
+Menu items can be shown or hidden at runtime using the `:if` option.
+
+    ActiveAdmin.register Post do
+      menu :if => proc{ current_admin_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 for the
@@ -74,30 +99,49 @@ To add the menu as a child of another menu:
 Note, the "Blog" menu does not even have to exist yet. It will be generated on
 the fly as a drop down list for you.
 
-### Menu Priority
+### Customizing Parent Menu Items
 
-By default Active Admin sorts menus alphabetically. Some times you want specific
-resources to show up at the beginning or the end of your menu.
+All of the options given to a standard menu item are also available to the
+parent menu items. You can customize their attributes in the Active Admin
+initializer.
 
-Each menu item is given an integer priority value (default 10). You can set it
-to edit the location of the menu item.
+    # config/initializers/active_admin.rb
+    ActiveAdmin.setup do |config|
+      config.namespace :admin do |admin|
 
-    ActiveAdmin.register Post do
-      menu :priority => 1
+        # This block will edit the default menu
+        admin.build_menu do |menu|
+          menu.add :label => "Blog", :priority => 0
+        end
+
+      end
     end
 
-This would ensure that the Post menu item, is at the beginning of the menu.
+Now, if you use `menu :parent => "Blog"`, your resource menu item will be a
+child of the Blog menu item with the priority of 0.
 
-### Conditionally Showing / Hiding Menu Items
+### Adding Custom Menu Items
 
-Menu items can be shown or hidden at runtime using the `:if` option.
+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.
 
-    ActiveAdmin.register Post do
-      menu :if => proc{ current_admin_user.can_edit_posts? }
+    # config/initializers/active_admin.rb
+    ActiveAdmin.setup do |config|
+      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
     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.
+This block will be run once on application startup to build the menu before each
+of the resources are added to it.
 
 ## Scoping the queries
 
@@ -160,3 +204,74 @@ If you need to completely replace the record retrieving code (e.g., you have a c
 In fact, the controllers use [Inherited Resource](https://github.com/josevalim/inherited_resources),
 so you can use all the
 [customization features in Inherited Resource](https://github.com/josevalim/inherited_resources#overwriting-defaults).
+
+
+## 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:
+
+    ActiveAdmin.register Project do
+    end
+
+    ActiveAdmin.register Ticket do
+      belongs_to :project
+    end
+
+Projects will be available as usual and tickets will be availble 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):
+
+    ActiveAdmin.register Project do
+
+      sidebar "Project Details" do
+        ul do
+          li link_to("Tickets", admin_project_tickets_path(project))
+          li link_to("Milestones", admin_project_milestones_path(project))
+        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
+seperate menu which you can use if you so wish. To use:
+
+    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 on user permissions or level.  For example:
+
+    ActiveAdmin.register Ticket do
+      belongs_to: :project
+      navigation_menu do
+        authorized?(:manage, SomeResource) ? :project : :restricted_menu
+      end
+    end

data/docs/3-index-pages.md

@@ -14,6 +14,44 @@ Built in, Active Admin has the following index renderers:
 All index pages also support scopes, filters, pagination, action items, and
 sidebar sections.
 
+## Multiple Index Pages
+
+Sometime you may want more than one index page for a resource to represent
+different views to the user. If multiple index pages exist, Active Admin will
+automatically build links at the top of the default index page. Including
+multiple views is simple and requires creating multiple index components in
+your resource.
+
+    index do
+      column :image_title
+      default_actions
+    end
+
+    index :as => :grid do |product|
+      link_to(image_tag(product.image_path), admin_product_path(product))
+    end
+
+The first index component will be the default index page unless you indicate
+otherwise by setting :default to true.
+
+    index do
+      column :image_title
+      default_actions
+    end
+
+    index :as => :grid, :default => true do |product|
+      link_to(image_tag(product.image_path), admin_product_path(product))
+    end
+
+Active Admin does not limit the index page to be a table, block, blog or grid.
+If you've [created your own index page](3-index-pages/create-an-index.md) it can be included by setting :as to the
+class of the index component you created.
+
+    index :as => ActiveAdmin::Views::IndexAsTable do
+      column :image_title
+      default_actions
+    end     
+
 ## Index Filters
 
 By default the index screen includes a "Filters" sidebar on the right hand side
@@ -112,3 +150,30 @@ You can remove links to download CSV, XML and JSON exports:
     index :download_links => false do
     end
 
+## Customizing Download Links
+
+There are multiple ways to either remove the download links per resource listing, or customize the formats that are shown.  Customize the formats by passing an array of symbols, or pass false to hide entirely.
+
+Customizing the download links per resource:
+
+    ActiveAdmin.register Post do
+
+      # hide the links entirely
+      index :download_links => false
+
+      # only show a PDF export
+      index :download_links => [:pdf]
+
+    end
+
+If you want to customize download links for every resource throughout the application, configure that in the `active_admin` initializer.
+
+    ActiveAdmin.setup do |config|
+
+      # Disable entirely
+      config.download_links = false
+
+      # Want PDF added to default download links
+      config.download_links = [:csv, :xml, :json, :pdf]
+
+    end