activeadmin-rails 1.7.0

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

@@ -0,0 +1,73 @@
+---
+layout: default
+parent: Customizing the Index Page
+nav_order: 3
+title: Index as a Blog
+redirect_from: /docs/3-index-pages/index-as-blog.html
+---
+
+# 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 of 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
+```

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

@@ -0,0 +1,31 @@
+---
+layout: default
+parent: Customizing the Index Page
+nav_order: 1
+title: Index as a Grid
+redirect_from: /docs/3-index-pages/index-as-grid.html
+---
+
+# 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.
+
+```ruby
+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 columns that are rendered using the columns
+option:
+
+```ruby
+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,259 @@
+---
+layout: default
+parent: Customizing the Index Page
+nav_order: 0
+title: Index as a Table
+redirect_from: /docs/3-index-pages/index-as-table.html
+---
+
+# Index as a Table
+
+The index page is a table with each of the models content columns and links to
+show, edit and delete the object.
+
+By default ActiveAdmin renders :index using `/app/views/active_admin/resource/index.html.arb`,
+which passes a paginated collection to `/app/views/active_admin/resource/_index_as_table.html.arb`:
+
+```ruby
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  id_column if resource_class.primary_key
+  active_admin_config.resource_columns.each do |attribute|
+    column attribute
+  end
+  actions
+end
+```
+
+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:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  column :title
+end
+```
+
+For association columns we make an educated guess on what to display by
+calling the following methods in the following order:
+
+```ruby
+: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:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  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.
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  column "Title" do |post|
+    link_to post.title, admin_post_path(post)
+  end
+end
+```
+
+## Defining Actions
+
+To setup links to View, Edit and Delete a resource, use the `actions` method:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  column :title
+  actions
+end
+```
+
+You can also append custom links to the default links:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  column :title
+  actions do |post|
+    item "Preview", admin_preview_post_path(post), class: "member_link"
+  end
+end
+```
+
+Or forego the default links entirely:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  column :title
+  actions defaults: false do |post|
+    item "View", admin_post_path(post)
+  end
+end
+```
+
+Or append custom action with custom html via arbre:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  column :title
+  actions do |post|
+    a "View", href: admin_post_path(post)
+  end
+end
+```
+
+In case you prefer to list actions links in a dropdown menu:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  column :title
+  actions dropdown: true do |post|
+    item "Preview", admin_preview_post_path(post)
+  end
+end
+```
+
+In addition, you can insert the position of the row in the greater collection by using the index_column special command:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  selectable_column
+  index_column
+  column :title
+end
+```
+
+index_column take an optional offset parameter to allow a developer to set the starting number for the index (default is 1).
+
+## 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.
+
+You can pass the key specifying the attribute which gets used to sort objects using Active Record.
+By default, this is the column on the resource's table that the attribute corresponds to.
+Otherwise, any attribute that the resource collection responds to can be used.
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  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:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  column :title, sortable: false
+end
+```
+
+It's also possible to sort by PostgreSQL's hstore column key. You should set `sortable`
+option to a `column->'key'` value:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  column :keywords, sortable: "meta->'keywords'"
+end
+```
+
+## Custom sorting
+
+It is also possible to use database specific expressions and options for sorting by column
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+order_by(:title) do |order_clause|
+   if order_clause.order == 'desc'
+     [order_clause.to_sql, 'NULLS LAST'].join(' ')
+   else
+     [order_clause.to_sql, 'NULLS FIRST'].join(' ')
+   end
+end
+
+index_table_for(collection, table_options) do |t|
+  column :title
+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:
+
+```ruby
+Admin::PostsController < ActiveAdmin::ResourceController
+  def apply_includes(collection)
+    collection.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:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  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:
+
+```ruby
+# /app/views/admin/posts/_index_as_table.html.arb
+index_table_for(collection, default_table_options) do |t|
+  column :title, sortable: false
+  column :secret_data if can? :manage, Post
+end
+```
+
+## Custom row class
+
+In order to add special class to table rows pass the proc object as a `:row_class` option
+of the `index` method.
+
+```ruby
+index row_class: ->elem { 'active' if elem.active? } do
+  # columns
+end
+```

data/docs/3-index-pages.md

@@ -0,0 +1,349 @@
+---
+layout: default
+nav_order: 3
+title: Customizing the Index Page
+redirect_from: /docs/3-index-pages.html
+has_children: true
+---
+
+# 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.
+
+```ruby
+index do
+  id_column
+  column :image_title
+  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.
+
+```ruby
+index do
+  column :image_title
+  actions
+end
+
+index as: :grid, default: true do |product|
+  link_to image_tag(product.image_path), admin_product_path(product)
+end
+```
+
+## Custom Index
+
+Active Admin does not limit the index page to be a table, block, blog or grid.
+If you've created your own [custom index](3-index-pages/custom-index.md) page it
+can be included by setting `:as` to the class of the index component you created.
+
+```ruby
+index as: ActiveAdmin::Views::IndexAsMyIdea do
+  column :image_title
+  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, customize `filters_form.html.erb`
+
+```erb
+# app/views/admin/posts/_filters_form.html.erb
+<%= active_admin_filters_form_for(@search,
+  title: { label: 'Title', as: :string },
+) %>
+```
+
+Out of the box, Active Admin supports the following filter types:
+
+* *:string* -  A drop down for selecting "Contains", "Equals", "Starts with",
+  "Ends with" and an input for a value.
+* *: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.
+
+```erb
+# app/views/admin/posts/_filters_form.html.erb
+<%= active_admin_filters_form_for(@search,
+  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.
+
+```erb
+# app/views/admin/posts/_filters_form.html.erb
+<%= active_admin_filters_form_for(@search,
+  author: { as: :check_boxes, collection: proc { Author.all } }
+) %>
+```
+
+To override options for string or numeric filter pass `filters` option.
+
+```erb
+# app/views/admin/posts/_filters_form.html.erb
+<%= active_admin_filters_form_for(@search,
+  title: { filters: [:starts_with, :ends_with] },
+) %>
+```
+
+Also, if you don't need the select with the options 'contains', 'equals',
+'starts_with' or 'ends_with' just add the option to the filter name with an
+underscore.
+
+For example:
+
+```erb
+# app/views/admin/posts/_filters_form.html.erb
+<%= active_admin_filters_form_for(@search,
+  name_equals: { as: :string },
+# or
+  name_contains: { as: :string },
+) %>
+```
+
+You can change the filter label by passing a label option:
+
+```erb
+# app/views/admin/posts/_filters_form.html.erb
+<%= active_admin_filters_form_for(@search,
+  author: { label: 'Something else' }
+) %>
+```
+
+By default, Active Admin will try to use ActiveModel I18n to determine the label.
+
+You can also filter on more than one attribute of a model using the [Ransack
+search predicate
+syntax](https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching).
+If using a custom search method, you will also need to specify the field type
+using `:as` and the label.
+
+```erb
+# app/views/admin/posts/_filters_form.html.erb
+<%= active_admin_filters_form_for(@search,
+  first_name_or_last_name_cont: { as: :string, label: "Name" }
+) %>
+```
+
+Filters can also be disabled for a resource, a namespace or the entire
+application.
+
+To disable for a specific resource:
+
+```ruby
+ActiveAdmin.configure_resource Post do |config|
+  config.filters = false
+end
+```
+
+To disable for a namespace, in the initializer:
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.namespace :my_namespace do |my_namespace|
+    my_namespace.filters = false
+  end
+end
+```
+
+Or to disable for the entire application:
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.filters = false
+end
+```
+
+You can also add a filter and still preserve the default filters:
+
+```ruby
+preserve_default_filters!
+filter :author
+```
+
+Or you can also remove a filter and still preserve the default filters:
+
+```ruby
+preserve_default_filters!
+remove_filter :id
+```
+
+## Index Scopes
+
+You can define custom scopes for your index page. This will add a tab bar above
+the index table to quickly filter your collection on pre-defined scopes. There
+are a number of ways to define your scopes:
+
+```ruby
+config.scope :all, default: true
+
+# assumes the model has a scope called ':active'
+config.scope :active
+
+# renames model scope ':leaves' to ':subcategories'
+config.scope "Subcategories", :leaves
+
+# Dynamic scope name
+config.scope ->{ Date.today.strftime '%A' }, :published_today
+
+# custom scope not defined on the model
+config.scope("Inactive") { |scope| scope.where(active: false) }
+
+# conditionally show a custom controller scope
+config.scope "Published", if: -> { current_admin_user.can? :manage, Posts } do |posts|
+  posts.published
+end
+```
+
+Scopes can be labelled with a translation, e.g.
+`activerecord.scopes.invoice.expired`.
+
+### Scopes groups
+
+You can assign group names to scopes to keep related scopes together and separate them from the rest.
+
+```ruby
+# a scope in the default group
+config.scope :all
+
+# two scopes used to filter by status
+config.scope :active, group: :status
+config.scope :inactive, group: :status
+
+# two scopes used to filter by date
+config.scope :today, group: :date
+config.scope :tomorrow, group: :date
+```
+
+## Index default sort order
+
+You can define the default sort order for index pages:
+
+```ruby
+ActiveAdmin.configure_resource Post do |config|
+  config.sort_order = 'name_asc'
+end
+```
+
+## Index pagination
+
+You can set the number of records per page as default:
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.default_per_page = 30
+end
+```
+
+You can set the number of records per page per resources:
+
+```ruby
+ActiveAdmin.configure_resource Post do |config|
+  config.per_page = 10
+end
+```
+
+Or allow users to choose themselves using dropdown with values
+
+```ruby
+ActiveAdmin.configure_resource Post do |config|
+  config.per_page = [10, 50, 100]
+end
+```
+
+You can change it per request / action too:
+
+```ruby
+class Admin::PostsController < ActiveAdmin::ResourceController
+  before_action only: :index do
+    @per_page = 100
+  end
+end
+```
+
+You can also disable pagination:
+
+```ruby
+ActiveAdmin.configure_resource Post do |config|
+  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:
+
+```ruby
+ActiveAdmin.configure_resource Post do |config|
+  config.set_page_options :index, pagination_total: false
+end
+```
+
+## Customizing Download Links
+
+You can easily remove or customize the download links you want displayed:
+
+```ruby
+# Per resource:
+ActiveAdmin.configure_resource Post do |config|
+
+  config.set_page_options :index, download_links: false
+  config.set_page_options :index, download_links: [:pdf]
+  config.set_page_options :index, download_links: proc{ current_user.can_view_download_links? }
+
+end
+
+# For the entire application:
+ActiveAdmin.setup do |config|
+
+  config.download_links = false
+  config.download_links = [:csv, :xml, :json, :pdf]
+  config.download_links = proc { current_user.can_view_download_links? }
+
+end
+```
+
+Note: you have to actually implement PDF rendering for your action, ActiveAdmin
+does not provide this feature. This setting just allows you to specify formats
+that you want to show up under the index collection.
+
+You'll need to use a PDF rendering library like PDFKit or WickedPDF to get the
+PDF generation you want.