aa-rails4 0.6.0

data/docs/3-index-pages.md

@@ -0,0 +1,191 @@
+# 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-block.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.
+
+## 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
+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.
+
+Filters can also be disabled for a resource, a namespace or the entire
+application.
+
+To disable for a specific resource:
+
+    ActiveAdmin.register Post do
+      config.filters = false
+    end
+
+To disable for a namespace, in the initializer:
+
+    ActiveAdmin.setup do |config|
+      config.namespace :my_namespace do |my_namespace|
+        my_namespace.filters = false
+      end
+    end
+
+Or to disable for the entire application:
+
+    ActiveAdmin.setup do |config|
+      config.filters = false
+    end
+
+You can also add a filter and still preserve the default filters:
+
+    preserve_default_filters!
+    filter :author
+
+## Index default sort order
+
+You can define the default sort order for index pages:
+
+    ActiveAdmin.register Post do
+      config.sort_order = "name_asc"
+    end
+
+## Index pagination
+
+
+You can set the number of records per page per resources:
+
+    ActiveAdmin.register Post do
+      config.per_page = 10
+    end
+
+You can also disable pagination:
+
+    ActiveAdmin.register Post do
+      config.paginate = false
+    end
+
+If you have a very large database, you might want to disable SELECT COUNT(*) queries caused by the pagination info at the bottom of the page:
+
+    ActiveAdmin.register Post do
+
+      # disable pagination total
+      index :pagination_total => false do
+        #...
+      end
+
+    end
+
+## Disable CSV, XML and JSON export
+
+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
+

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,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_product_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_product_path(product))
+    end

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

@@ -0,0 +1,120 @@
+<!-- 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
+
+For association columns we make an educated guess on what to display by
+calling the following methods in the following order:
+
+    :display_name, :full_name, :name, :username, :login, :title, :email, :to_s
+
+This can be customized in config/initializers/active_admin.rb.
+
+If the default title does not work for you, pass it as the first argument:
+
+    index do
+      column "My Custom Title", :title
+    end
+
+Sometimes that just isn't enough and you need to write some view-specific code.
+For example, say we wanted a "Title" column that links to the posts admin screen.
+
+`column` accepts a block that will be rendered for each of the objects in the collection.
+The block is called once for each resource, which is passed as an argument to the block.
+
+    index do
+      column "Title" do |post|
+        link_to post.title, admin_post_path(post)
+      end
+    end
+
+To setup links to View, Edit and Delete a resource, use the `actions` method:
+
+    index do
+      column :title
+      actions
+    end
+
+You can also append custom links to the default links:
+
+    index do
+      column :title
+      actions do |post|
+        link_to "Preview", admin_preview_post_path(post), :class => "member_link"
+      end
+    end
+
+Or forego the default links entirely:
+
+    index do
+      column :title
+      actions :defaults => false 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
+
+## Associated Sorting
+
+You're normally able to sort columns alphabetically, but by default you
+can't sort by associated objects. Though with a few simple changes, you can.
+
+Assuming you're on the Books index page, and Book has_one Publisher:
+
+    controller do
+      def scoped_collection
+        resource_class.includes(:publisher) # prevents N+1 queries to your database
+      end
+    end
+
+Then it's simple to sort by any Publisher attribute from within the index table:
+
+    index do
+      column :publisher, sortable: 'publishers.name'
+    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,32 @@
+# 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
+
+You can set custom csv options:
+
+    ActiveAdmin.register Post do
+      csv :force_quotes => true do
+        column :title
+        column("Author") { |post| post.author.full_name }
+      end
+    end
+
+You can set options for the CSV format system-wide:
+
+    # config/initializers/active_admin.rb
+    # Set the CSV builder separator
+    config.csv_options = { :col_sep => ';' }
+
+    # Force the use of quotes
+    config.csv_options = { :force_quotes => true }