activeadmin 0.2.2 → 0.3.0

data/docs/3-index-pages.md

@@ -0,0 +1,55 @@
+# Customizing the Index Page
+
+Filtering and listing resources is one of the most important tasks for
+administering a web application. Active Admin provides many different tools for
+you to build a compelling interface into your data for the admin staff.
+
+Built in, Active Admin has the following index renderers:
+
+* *Table*: A table drawn with each row being a resource ([View Table Docs](3-index-pages/index-as-table.md))
+* *Grid*: A set of rows and columns each cell being a resource ([View Grid Docs](3-index-pages/index-as-grid.md))
+* *Blocks*: A set of rows (not tabular) each row being a resource ([View Blocks Docs](3-index-pages/index-as-blocks.md))
+* *Blog*: A title and body content, similar to a blog index ([View Blog Docs](3-index-pages/index-as-blog.md))
+
+All index pages also support scopes, filters, pagination, action items, and
+sidebar sections.
+
+## Index Filters
+
+By default the index screen includes a "Filters" sidebar on the right hand side
+with a filter for each attribute of the registered model. You can customize the
+filters that are displayed as well as the type of widgets they use.
+
+To display a filter for an attribute, use the filter method
+
+    ActiveAdmin.register Post do
+      filter :title
+    end
+
+Out of the box, Active Admin supports the following filter types:
+
+* *:string* - A search field
+* *:date_range* - A start and end date field with calendar inputs
+* *:numeric* - A drop down for selecting "Equal To", "Greater Than" or "Less
+  Than" and an input for a value.
+* *:select* - A drop down which filters based on a selected item in a collection
+  or all.
+* *:check_boxes* - A list of check boxes users can turn on and off to filter
+
+By default, Active Admin will pick the most relevant filter based on the
+attribute type. You can force the type by passing the :as option.
+
+    filter :author, :as => :check_boxes
+
+The :check_boxes and :select types accept options for the collection. By default
+it attempts to create a collection based on an association. But you can pass in
+the collection as a proc to be called at render time.
+
+    # Will call available
+    filter :author, :as => :check_boxes, :collection => proc { Author.all }
+
+You can change the filter label by passing a label option:
+
+    filter :author, :label => 'Author'
+
+By default, Active Admin will try to use ActiveModel I18n to determine the label.

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

@@ -0,0 +1,16 @@
+<!-- Please don't edit this file. It will be clobbered. -->
+
+# 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.
+
+    index :as => :block do |product|
+      div :for => product do
+        h2 auto_link(product.title)
+        div do
+          simple_format product.description
+        end
+      end
+    end

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

@@ -0,0 +1,61 @@
+<!-- Please don't edit this file. It will be clobbered. -->
+
+# Index as Blog
+
+Render your index page as a set of posts. The post has two main options:
+title and body.
+
+  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:
+
+    index :as => :blog do
+      title :a_method_to_call
+    end
+
+This will result in the title of the post being the return value of
+Resource#a_method_to_call
+
+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:
+
+    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:
+
+    index :as => :blog do
+      title :my_title
+      body :my_body # Return value of #my_body will be the body
+    end
+
+Or, render a block as the body:
+
+    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

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

@@ -0,0 +1,21 @@
+<!-- Please don't edit this file. It will be clobbered. -->
+
+# Index as a Grid
+
+Sometimes you want to display the index screen for a set of resources as a grid
+(possibly a grid of thumbnail images). To do so, use the :grid option for the
+index block.
+
+    index :as => :grid do |product|
+      link_to(image_tag(product.image_path), admin_products_path(product))
+    end
+
+The block is rendered within a cell in the grid once for each resource in the
+collection. The resource is passed into the block for you to use in the view.
+
+You can customize the number of colums that are rendered using the columns
+option:
+
+    index :as => :grid, :columns => 5 do |product|
+      link_to(image_tag(product.image_path), admin_products_path(product))
+    end

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

@@ -0,0 +1,90 @@
+<!-- Please don't edit this file. It will be clobbered. -->
+
+# Index as a Table
+
+By default, the index page is a table with each of the models content columns and links to
+show, edit and delete the object. There are many ways to customize what gets
+displayed.
+
+## Defining Columns
+
+To display an attribute or a method on a resource, simply pass a symbol into the
+column method:
+
+    index do
+      column :title
+    end
+
+If the default title does not work for you, pass it as the first argument:
+
+    index do
+      column "My Custom Title", :title
+    end
+
+Sometimes calling methods just isn't enough and you need to write some view
+specific code. For example, say we wanted a colum called Title which holds a
+link to the posts admin screen.
+
+The column method accepts a block as an argument which will then be rendered
+within the context of the view for each of the objects in the collection.
+
+    index do
+      column "Title" do |post|
+        link_to post.title, admin_post_path(post)
+      end
+    end
+
+The block gets called once for each resource in the collection. The resource gets passed into
+the block as an argument.
+
+To setup links to View, Edit and Delete a resource, use the default_actions method:
+
+    index do
+      column :title
+      default_actions
+    end
+
+Alternatively, you can create a column with custom links:
+
+    index do
+      column :title
+      column "Actions" do |post|
+        link_to "View", admin_post_path(post)
+      end
+    end
+
+
+## Sorting
+
+When a column is generated from an Active Record attribute, the table is
+sortable by default. If you are creating a custom column, you may need to give
+Active Admin a hint for how to sort the table.
+
+If a column is defined using a block, you must pass the key to turn on sorting. The key
+is the attribute which gets used to sort objects using Active Record.
+
+    index do
+      column "Title", :sortable => :title do |post|
+        link_to post.title, admin_post_path(post)
+      end
+    end
+
+You can turn off sorting on any column by passing false:
+
+    index do
+      column :title, :sortable => false
+    end
+
+## Showing and Hiding Columns
+
+The entire index block is rendered within the context of the view, so you can
+easily do things that show or hide columns based on the current context.
+
+For example, if you were using CanCan:
+
+    index do
+      column :title, :sortable => false
+      if can? :manage, Post
+        column :some_secret_data
+      end
+    end

data/docs/4-csv-format.md

@@ -0,0 +1,14 @@
+# Customizing the CSV format
+
+Active Admin provides CSV file downloads on the index screen for each Resource.
+By default it will render a CSV file with all the content columns of your
+registered model.
+
+Customizing the CSV format is as simple as customizing the index page.
+
+    ActiveAdmin.register Post do
+      csv do
+        column :title
+        column("Author") { |post| post.author.full_name }
+      end
+    end

data/docs/5-forms.md

@@ -0,0 +1,39 @@
+# Customizing the Form
+
+Active Admin gives complete control over the output of the form by creating a thin DSL on top of
+the fabulous DSL created by Formtastic (http://github.com/justinfrench/formtastic).
+
+    ActiveAdmin.register Post do
+
+      form do |f|
+        f.inputs "Details" do
+          f.input :title
+          f.input :published_at, :label => "Publish Post At"
+          f.input :category
+        end
+        f.inputs "Content" do
+          f.input :body
+        end
+        f.buttons
+      end
+
+    end
+
+Please view the documentation for Formtastic to see all the wonderful things you can do:
+http://github.com/justinfrench/formtastic
+
+If you require a more custom form than can be provided through the DSL, you can pass
+a partial in to render the form yourself.
+
+For example:
+
+    ActiveAdmin.register Post do
+      form :partial => "form"
+    end
+
+Then implement app/views/admin/posts/_form.html.erb:
+
+    <%= semantic_form_for [:admin, @post] do |f| %>
+      <%= f.inputs :title, :body %>
+      <%= f.buttons :commit %>
+    <% end %>

data/docs/6-show-screens.md

@@ -0,0 +1,22 @@
+# Customizing the Show Screen
+
+Customizing the show screen is as simple as implementing the show block:
+
+    ActiveAdmin.register Post do
+      show do
+        h3 post.title
+        div do
+          simple_format post.body
+        end
+      end
+    end
+
+The show block is rendered within the context of the view and uses the Arbre HTML DSL. You
+can also render a partial at any point.
+
+    ActiveAdmin.register Post do
+      show do
+        # renders app/views/admin/posts/_some_partial.html.erb
+        render "some_partial"
+      end
+    end

data/docs/7-sidebars.md

@@ -0,0 +1,35 @@
+# Sidebar Sections
+
+To add a sidebar section to all the screen within a section, use the sidebar method:
+
+    sidebar :help do
+      "Need help? Email us at help@example.com"
+    end
+
+This will generate a sidebar section on each screen of the resource. With the block as
+the contents of the section. The first argument is the section title.
+
+You can also use Arbre syntax to define the content.
+
+    sidebar :help do
+      ul do
+        li "Second List First Item"
+        li "Second List Second Item"
+      end
+    end
+
+Sidebar sections can be rendered on a specific action by using the :only or :except
+options.
+
+    sidebar :help, :only => :index do
+      "Need help? Email us at help@example.com"
+    end
+
+If you only pass a symbol, Active Admin will attempt to locate a partial to render.
+
+    # Will render app/views/admin/posts/_help_sidebar.html.erb
+    sidebar :help
+
+Or you can pass your own custom partial to render.
+
+    sidebar :help, :partial => "custom_help_partial"

data/docs/8-custom-actions.md

@@ -0,0 +1,123 @@
+# Custom Controller Actions
+
+Active Admin allows you to override and modify the underlying controller which
+is generated for you. There are helpers to add collection and member actions, or
+you can drop right in to the controller and modify its behavior.
+
+## Collection Actions
+
+A collection action is a controller action which operates on the collection of
+resources. This method adds both the action to the controller as well as
+generating a route for you.
+
+To add a collection action, use the collection_action method:
+
+
+    ActiveAdmin.register Post do
+
+      collection_action :import_csv, :method => :post do
+        # Do some CSV importing work here...
+        redirect_to :action => :index, :notice => "CSV imported successfully!"
+      end
+
+    end
+
+This collection action will generate a route at "/admin/posts/import_csv"
+pointing to the Admin::PostsController#import_csv controller action.
+
+## Member Actions
+
+A member action is a controller action which operates on a single resource.
+
+For example, to add a lock action to a user resource, you would do the
+following:
+
+    ActiveAdmin.register User do
+
+      member_action :lock, :method => :put do
+        user = User.find(params[:id])
+        user.lock!
+        redirect_to :action => :show, :notice => "Locked!"
+      end
+
+    end
+
+This will generate a route at "/admin/users/:id/lock" pointing to the
+Admin::UserController#lock controller action.
+
+## Controller Action HTTP Verb
+
+The collection_action and member_actions methods both accept the "method"
+argument to set the HTTP verb for the controller action and route.
+
+The generated routes will be scoped to the given method you pass in. By default
+your action will use the :get verb.
+
+## Rendering in Custom Actions
+
+Custom controller actions support rendering within the standard Active Admin
+layout. 
+
+    ActiveAdmin.register Post do
+
+      # /admin/posts/:id/comments
+      member_action :comments do
+        @post = Post.find(params[:id])
+
+        # This will render app/views/admin/posts/comments.html.erb
+      end
+
+    end
+
+If you would like to use the same view syntax as the rest of Active Admin, you
+can use the Arbre file extension: .arb.
+
+For example, create app/views/admin/posts/comments.html.arb with:
+
+    table_for assigns[:post].comments do
+      column :id
+      column :author
+      column :body do |comment|
+        simple_format comment.body
+      end
+    end
+
+### Page Titles
+
+The page title for the custom action will be the internationalized version of
+the controller action name. For example, a member_action named "upload_csv" will
+look up a translation key of "active_admin.upload_csv". If none are found, it
+just title cases the controller action's name.
+
+If this method doesn't work for your requirements, you can always set the
+@page_title instance variable in your controller action to customize the page
+title.
+
+    ActiveAdmin.register Post do
+
+      # /admin/posts/:id/comments
+      member_action :comments do
+        @post = Post.find(params[:id])
+        @page_title = "#{@post.title}: Comments" # Set the page title
+
+        # This will render app/views/admin/posts/comments.html.erb
+      end
+
+    end
+
+## Modify the Controller
+
+The generated controller is available to you within the registration block by
+using the #controller method.
+
+    ActiveAdmin.register Post do
+
+      controller do
+        # This code is evaluated within the controller class
+
+        def define_a_method
+          # Instance method
+        end
+      end
+
+    end