activeadmin 2.2.0

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

@@ -0,0 +1,27 @@
+---
+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,227 @@
+---
+redirect_from: /docs/3-index-pages/index-as-table.html
+---
+
+# 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:
+
+```ruby
+index do
+  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
+index do
+  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
+index do
+  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
+index do
+  selectable_column
+  column :title
+  actions
+end
+```
+
+You can also append custom links to the default links:
+
+```ruby
+index do
+  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
+index do
+  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
+index do
+  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
+index do
+  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
+index do
+  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
+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:
+
+```ruby
+index do
+  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
+index do
+  column :keywords, sortable: "meta->'keywords'"
+end
+```
+
+## Custom sorting
+
+It is also possible to use database specific expressions and options for sorting by column
+
+```ruby
+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 do
+  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
+controller do
+  def scoped_collection
+    super.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
+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:
+
+```ruby
+index do
+  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/4-csv-format.md

@@ -0,0 +1,74 @@
+---
+redirect_from: /docs/4-csv-format.html
+---
+
+# 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.
+
+```ruby
+ActiveAdmin.register Post do
+  csv do
+    column :title
+    column(:author) { |post| post.author.full_name }
+    column('bODY', humanize_name: false) # preserve case
+  end
+end
+```
+
+You can also set custom CSV settings for an individual resource:
+
+```ruby
+ActiveAdmin.register Post do
+  csv force_quotes: true, col_sep: ';', column_names: false do
+    column :title
+    column(:author) { |post| post.author.full_name }
+  end
+end
+```
+
+Or system-wide:
+
+```ruby
+# 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 }
+```
+
+You can customize the filename by overriding `csv_filename` in the controller block.
+
+```ruby
+ActiveAdmin.register User do
+  controller do
+    def csv_filename
+      'User Details.csv'
+    end
+  end
+end
+```
+
+## Streaming
+
+By default Active Admin streams the CSV response to your browser as it's generated.
+This is good because it prevents request timeouts, for example the infamous H12
+error on Heroku.
+
+However if an exception occurs while generating the CSV, the request will eventually
+time out, with the last line containing the exception message. CSV streaming is
+disabled in development to help debug these exceptions. That lets you use tools like
+better_errors and web-console to debug the issue. If you want to customize the
+environments where CSV streaming is disabled, you can change this setting:
+
+```ruby
+# config/initializers/active_admin.rb
+
+config.disable_streaming_in = ['development', 'staging']
+```

data/docs/5-forms.md

@@ -0,0 +1,232 @@
+---
+redirect_from: /docs/5-forms.html
+---
+
+# Forms
+
+Active Admin gives you complete control over the output of the form by creating
+a thin DSL on top of [Formtastic](https://github.com/justinfrench/formtastic):
+
+```ruby
+ActiveAdmin.register Post do
+
+  form title: 'A custom title' do |f|
+    inputs 'Details' do
+      input :title
+      input :published_at, label: "Publish Post At"
+      li "Created at #{f.object.created_at}" unless f.object.new_record?
+      input :category
+    end
+    panel 'Markup' do
+      "The following can be used in the content below..."
+    end
+    inputs 'Content', :body
+    para "Press cancel to return to the list without saving."
+    actions
+  end
+
+end
+```
+
+For more details, please see [Formtastic's documentation](https://github.com/justinfrench/formtastic/wiki).
+
+## Default
+
+Resources come with a default form defined as such:
+
+```ruby
+form do |f|
+  f.semantic_errors # shows errors on :base
+  f.inputs          # builds an input field for every attribute
+  f.actions         # adds the 'Submit' and 'Cancel' buttons
+end
+```
+
+## Partials
+
+If you want to split a custom form into a separate partial use:
+
+```ruby
+ActiveAdmin.register Post do
+  form partial: 'form'
+end
+```
+
+Which looks for something like this:
+
+```ruby
+# app/views/admin/posts/_form.html.arb
+insert_tag active_admin_form_for resource do |f|
+  inputs :title, :body
+  actions
+end
+```
+
+This is a regular Rails partial so any template engine may be used.
+
+You can also use the `ActiveAdmin::FormBuilder` as builder in your Formtastic
+Form for use the same helpers are used in the admin file:
+
+```ruby
+  = semantic_form_for [:admin, @post], builder: ActiveAdmin::FormBuilder do |f|
+    = f.inputs "Details" do
+      = f.input :title
+    - f.has_many :taggings, sortable: :position, sortable_start: 1 do |t|
+      - t.input :tag
+    = f.actions
+
+```
+
+## Nested Resources
+
+You can create forms with nested models using the `has_many` method, even if
+your model uses `has_one`:
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params :title,
+                :published_at,
+                :body,
+                categories_attributes: [:id, :title, :_destroy],
+                taggings_attributes: [:id, :tag],
+                comment_attributes: [:id, :body, :_destroy]
+
+  form do |f|
+    f.inputs 'Details' do
+      f.input :title
+      f.input :published_at, label: 'Publish Post At'
+    end
+    f.inputs 'Content', :body
+    f.inputs do
+      f.has_many :categories, heading: 'Themes',
+                              allow_destroy: true,
+                              new_record: false do |a|
+        a.input :title
+      end
+    end
+    f.inputs do
+      f.has_many :taggings, sortable: :position, sortable_start: 1 do |t|
+        t.input :tag
+      end
+    end
+    f.inputs do
+      f.has_many :comment,
+                 new_record: 'Leave Comment',
+                 allow_destroy: -> (c) { c.author?(current_admin_user) } do |b|
+        b.input :body
+      end
+    end
+    f.actions
+  end
+
+end
+```
+
+*NOTE*: In addition to using `has_many` as illustrated above, you'll need to add
+`accepts_nested_attributes` to your parent model and [configure strong parameters](https://activeadmin.info/2-resource-customization.html)
+
+The `:allow_destroy` option adds a checkbox to the end of the nested form allowing
+removal of the child object upon submission. Be sure to set `allow_destroy: true`
+on the association to use this option. It is possible to associate
+`:allow_destroy` with a string or a symbol, corresponding to the name of a child
+object's method that will get called, or with a Proc object. The Proc object
+receives the child object as a parameter and should return either true or false.
+
+The `:heading` option adds a custom heading. You can hide it entirely by passing
+`false`.
+
+The `:new_record` option controls the visibility of the new record button (shown
+by default).  If you pass a string, it will be used as the text for the new
+record button.
+
+The `:sortable` option adds a hidden field and will enable drag & drop sorting
+of the children. It expects the name of the column that will store the index of
+each child.
+
+The `:sortable_start` option sets the value (0 by default) of the first position
+in the list.
+
+## Datepicker
+
+ActiveAdmin offers the `datepicker` input, which uses the [jQuery UI
+datepicker](http://jqueryui.com/datepicker/).  The datepicker input accepts any
+of the options available to the standard jQueryUI Datepicker. For example:
+
+```ruby
+form do |f|
+  f.input :starts_at, as: :datepicker,
+                      datepicker_options: {
+                        min_date: "2013-10-8",
+                        max_date: "+3D"
+                      }
+
+  f.input :ends_at, as: :datepicker,
+                    datepicker_options: {
+                      min_date: 3.days.ago.to_date,
+                      max_date: "+1W +5D"
+                    }
+end
+```
+
+Datepicker also accepts the `:label` option as a string or proc to display.
+If it's a proc, it will be called each time the datepicker is rendered.
+
+## Displaying Errors
+
+To display a list of all validation errors:
+
+```ruby
+form do |f|
+  f.semantic_errors *f.object.errors.keys
+  # ...
+end
+```
+
+This is particularly useful to display errors on virtual or hidden attributes.
+
+# Tabs
+
+You can arrange content in tabs as shown below:
+
+```ruby
+  form do |f|
+    tabs do
+      tab 'Basic' do
+        f.inputs 'Basic Details' do
+          f.input :email
+          f.input :password
+          f.input :password_confirmation
+        end
+      end
+
+      tab 'Advanced', html_options: { class: 'specific_css_class' } do
+        f.inputs 'Advanced Details' do
+          f.input :role
+        end
+      end
+    end
+    f.actions
+  end
+```
+
+`html_options` allows you set additional html params for tab's menu item.
+
+# Customize the Create Another checkbox
+
+In order to simplify creating multiple resources you may enable ActiveAdmin to
+show nice "Create Another" checkbox alongside of Create Model button. It may be
+enabled for the whole application:
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.create_another = true
+end
+```
+
+or for the particular resource:
+
+```ruby
+ActiveAdmin.register Post do
+  config.create_another = true
+end
+```