yousty-activeadmin 1.0.0.pre

data/docs/13-authorization-adapter.md

@@ -0,0 +1,227 @@
+# 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 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
+
+    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
+    
+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)).
+```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:
+
+    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 initialize(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

@@ -0,0 +1,340 @@
+# 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/post.rb` file like so:
+
+```ruby
+ActiveAdmin.register Post do
+  # everything happens here :D
+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:
+
+```ruby
+ActiveAdmin.register Post do
+  controller do
+    def permitted_params
+      params.permit post: [:title, :content, :author]
+    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
+```
+
+## 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`.
+
+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:
+
+```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
+```
+
+## Customizing resource retrieval
+
+A common way to increase page performance is to elimate N+1 queries by eager loading associations:
+
+```ruby
+ActiveAdmin.register Post do
+  controller do
+    def scoped_collection
+      super.includes :author, :categories
+    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 resource
+      Post.where(id: params[:id]).first!
+    end
+  end
+end
+```
+
+Our controllers are built on [Inherited Resources](https://github.com/josevalim/inherited_resources),
+so you can use [all of its features](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:
+
+```ruby
+ActiveAdmin.register Project
+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):
+
+```ruby
+ActiveAdmin.register Project do
+
+  sidebar "Project Details", only: [:show, :edit] 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:
+
+```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
+```

data/docs/3-index-pages/create-an-index.md

@@ -0,0 +1,29 @@
+# Create an Index
+
+If the supplied Active Admin index components are insufficient for your project
+feel free to define your own. Index classes extend ActiveAdmin::Component and
+require a build method and an index_name class method.
+
+    module ActiveAdmin
+      module Views
+      	class IndexAsMyIdea < ActiveAdmin::Component
+
+          def build(page_presenter, collection)
+            ...
+          end
+
+          def self.index_name
+            "my_idea"
+          end
+
+        end
+      end
+    end
+
+The build method takes a PagePresenter object and collection of whatever you
+choose.
+
+The index_name class method takes no arguments and returns a string that should
+be representative of the the class name. If this method is not defined, your
+index component will not be able take advantage of Active Admin's
+*multiple index pages* feature.

data/docs/3-index-pages/index-as-block.md

@@ -0,0 +1,21 @@
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
+
+# Index as a Block
+
+If you want to fully customize the display of your resources on the index
+screen, Index as a Block allows you to render a block of content for each
+resource.
+
+```ruby
+index as: :block do |product|
+  div for: product do
+    resource_selection_cell product
+    h2  auto_link     product.title
+    div simple_format product.description
+  end
+end
+```

data/docs/3-index-pages/index-as-blog.md

@@ -0,0 +1,71 @@
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
+
+# Index as Blog
+
+Render your index page as a set of posts. The post has two main options:
+title and body.
+
+```ruby
+index as: :blog do
+  title :my_title # Calls #my_title on each resource
+  body  :my_body  # Calls #my_body on each resource
+end
+```
+
+## Post Title
+
+The title is the content that will be rendered within a link to the
+resource. There are two main ways to set the content for the title
+
+First, you can pass in a method to be called on your resource. For example:
+
+```ruby
+index as: :blog do
+  title :a_method_to_call
+end
+```
+
+Second, you can pass a block to the tile option which will then be
+used as the contents fo the title. The resource being rendered
+is passed in to the block. For Example:
+
+```ruby
+index as: :blog do
+  title do |post|
+    span post.title,      class: 'title'
+    span post.created_at, class: 'created_at'
+  end
+end
+```
+
+## Post Body
+
+The body is rendered underneath the title of each post. The same two
+style of options work as the Post Title above.
+
+Call a method on the resource as the body:
+
+```ruby
+index as: :blog do
+  title :my_title
+  body :my_body
+end
+```
+
+Or, render a block as the body:
+
+```ruby
+index as: :blog do
+  title :my_title
+  body do |post|
+    div truncate post.title
+    div class: 'meta' do
+      span "Post in #{post.categories.join(', ')}"
+    end
+  end
+end
+```