activeadmin-rails 1.7.0

data/docs/4-csv-format.md

@@ -0,0 +1,86 @@
+---
+layout: default
+nav_order: 4
+title: CSV Format
+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.
+
+To customize the CSV format override [csv_builder]:
+
+```ruby
+class Admin::PostsController < ActiveAdmin::ResourceController
+  protected
+  def csv_builder
+    @csv_builder ||= ActiveAdmin::CSVBuilder.new(resource: active_admin_config) do
+      column :title
+      column(:author) { |post| post.author.full_name }
+      column('bODY', humanize_name: false) # preserve case
+    end
+  end
+end
+```
+
+You can also set custom CSV settings:
+
+```ruby
+class Admin::PostsController < ActiveAdmin::ResourceController
+  protected
+  def csv_builder
+    @csv_builder ||= ActiveAdmin::CSVBuilder.new(resource: active_admin_config, force_quotes: true, col_sep: ';', column_names: false) do
+      column :title
+      column(:author) { |post| post.author.full_name }
+    end
+  end
+end
+```
+
+Or system-wide in `config/initializers/active_admin.rb`:
+
+```ruby
+Rails.application.reloader.to_prepare do
+  ActiveAdmin.setup do |config|
+    # 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
+class Admin::UsersController < ActiveAdmin::ResourceController
+  protected
+    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 in `config/initializers/active_admin.rb`:
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.disable_streaming_in = ['development', 'staging']
+  ...
+```
+
+[csv_builder]: https://rubydoc.info/github/varyonic/activeadmin/master/ActiveAdmin/ResourceController/Streaming#csv_builder-instance_method
+[csv_filename]: https://rubydoc.info/github/varyonic/activeadmin/master/ActiveAdmin/ResourceController/Streaming#csv_filename-instance_method

data/docs/5-forms.md

@@ -0,0 +1,233 @@
+---
+layout: default
+nav_order: 5
+title: Forms
+redirect_from: /docs/5-forms.html
+---
+
+# Forms
+
+## Default
+
+Active Admin renders `:create` and `:update` by default using partial `form` 
+which in turn by default uses an Arbo component `active_admin_form_for`
+that wraps and extends [Formtastic].
+
+The default `_form` partial is located in `app/views/active_admin/resource/_form.html.arb`:
+
+```ruby
+options = {
+  url: resource.persisted? ? resource_path(resource) : collection_path,
+  as: active_admin_config.param_key
+}
+options.merge!(page_presenter.options)
+
+active_admin_form_for(resource, options) do |f|
+  f.semantic_errors # show errors on :base by default
+  f.inputs
+  f.actions
+end
+```
+
+## Partials
+
+A customized `app/views/admin/posts/_form.html.arb` might look like:
+
+```ruby
+content_for(:page_title) { 'A custom title' }
+
+active_admin_form_for(resource) 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
+```
+
+This is a regular Rails partial so any template engine may be used, eg. haml.
+
+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
+
+```
+
+For more details, please see [Formtastic's documentation].
+
+## Nested Resources
+
+You can create forms with nested models using the `has_many` method, even if
+your model uses `has_one`:
+
+```ruby
+class Admin::PostsController < ActiveAdmin::ResourceController
+  protected
+  def permitted_attr_names
+    [
+      :title,
+      :published_at,
+      :body, 
+      categories_attributes: [:id, :title, :_destroy], 
+      taggings_attributes: [:id, :tag], 
+      comment_attributes: [:id, :body, :_destroy]
+    ]
+  end
+end
+```
+
+```ruby
+# app/views/admin/posts/_form.html.arb
+active_admin_form_for(resource) 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
+```
+
+*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.org/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
+active_admin_form_for(resource) 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
+active_admin_form_for(resource) 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
+active_admin_form_for(resource) 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.configure_resource Post do |config|
+  config.create_another = true
+end
+```
+
+[Formtastic]: https://github.com/justinfrench/formtastic
+[Formtastic's documentation]: https://github.com/justinfrench/formtastic/wiki

data/docs/6-show-pages.md

@@ -0,0 +1,61 @@
+---
+layout: default
+nav_order: 6
+title: Show Pages
+redirect_from: /docs/6-show-pages.html
+---
+# Customize the Show Page
+
+Active Admin renders `:show` using partial `show`
+
+The default partial is located in `app/views/active_admin/resource/_show.html.arb` and simply renders `attributes_panel`
+
+A customized `app/views/admin/posts/_show.html.arb` keeping the default AA look might look like:
+
+```ruby
+content_for(:page_title) { resource.name }
+attributes_table do
+  row :title
+  row :image do |ad|
+    image_tag ad.image.url
+  end
+end
+active_admin_comments_for(resource)
+```
+
+A more generic partial might look like:
+
+```ruby
+h3 post.title
+div do
+  simple_format post.body
+end
+```
+
+If you want a more data-dense page, you can combine a sidebar:
+
+```ruby
+panel "Table of Contents" do
+  table_for book.chapters do
+    column :number
+    column :title
+    column :page
+  end
+end
+active_admin_comments_for(resource)
+```
+
+and
+
+```ruby
+ActiveAdmin.register Book do
+  sidebar "Details", only: :show do
+    attributes_table_for book do
+      row :title
+      row :author
+      row :publisher
+      row('Published?') { |b| status_tag b.published? }
+    end
+  end
+end
+```

data/docs/7-sidebars.md

@@ -0,0 +1,63 @@
+---
+layout: default
+nav_order: 7
+title: Sidebars
+redirect_from: /docs/7-sidebars.html
+---
+# Sidebar Sections
+
+Sidebars allow you to put whatever content you want on the side of the page.
+
+```ruby
+config.add_sidebar_section :help
+
+# app/views/admin/posts/_help_sidebar.html.arb
+"Need help? Email us at help@example.com"
+```
+
+This will generate a sidebar on every page for that resource. The first
+argument is used as the title, and can be a symbol, string, or lambda.
+
+Sidebars can be rendered on a specific action by passing `:only` or `:except`.
+
+```ruby
+config.add_sidebar_section :help, only: :index
+```
+
+If you want to conditionally display a sidebar section, use the :if option and
+pass it a proc which will be rendered within the view context.
+
+```ruby
+config.add_sidebar_section :help, if: proc{ current_admin_user.super_admin? }
+```
+
+You can access your model as resource in the sidebar too:
+
+```ruby
+# app/views/admin/posts/_custom_sidebar.html.arb
+resource.a_method
+```
+
+You can also override the partial name:
+
+```ruby
+config.add_sidebar_section :help                    # app/views/admin/posts/_help_sidebar.html.erb
+config.add_sidebar_section :help, partial: 'custom' # app/views/admin/posts/_custom.html.erb
+```
+
+It's possible to add custom class name to the sidebar parent element by passing
+`class` option:
+
+```ruby
+config.add_sidebar_section :help, class: 'custom_class'
+```
+
+By default sidebars are positioned in the same order as they defined, but it's also
+possible to specify their position manually:
+
+```ruby
+# will push Help section to the top (above default Filters section)
+config.add_sidebar_section :help, priority: 0
+```
+
+Default sidebar priority is `10`.

data/docs/8-custom-actions.md

@@ -0,0 +1,160 @@
+---
+layout: default
+nav_order: 8
+title: Custom Actions
+redirect_from: /docs/8-custom-actions.html
+---
+
+# Custom Controller Actions
+
+Add custom actions the Rails Way:
+
+## Collection Actions
+
+A collection action is a controller action which operates on the collection of
+resources. Add both the action to the controller as well as a route.
+
+```ruby
+class Admin::PostsController < ActiveAdmin::ResourceController
+  def import_csv
+    # Do some CSV importing work here...
+    redirect_to collection_path, notice: "CSV imported successfully!"
+  end
+end
+```
+and
+
+```ruby
+Rails.application.routes.draw do
+  post '/admin/posts/import_csv', controller: 'admin/posts', action: 'import_csv'
+  ...
+```
+
+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:
+
+```ruby
+class Admin::UsersController < ActiveAdmin::ResourceController
+  def lock
+    resource.lock!
+    redirect_to resource_path, notice: "Locked!"
+  end
+```
+and
+```ruby
+Rails.application.routes.draw do
+  put '/admin/users/:id/lock', controller: 'admin/users', action: 'lock'
+  ...
+```
+
+## HTTP Verbs
+
+Sometimes you want to create an action that handles multiple
+HTTP verbs. In that case, this is the suggested approach:
+
+```ruby
+def foo
+  if request.post?
+    resource.update_attributes! foo: params[:foo] || {}
+    head :ok
+  else
+    render :foo
+  end
+end
+```
+and
+```ruby
+Rails.application.routes.draw do
+  get 'admin/users/:id/foo', container: 'admin/users', action: 'foo'
+  post 'admin/users/:id/foo', container: 'admin/users', action: 'foo'
+  ...
+```
+
+## Rendering
+
+Custom controller actions support rendering within the standard Active Admin
+layout.
+
+```ruby
+class Admin::PostsController < ActiveAdmin::ResourceController
+  # /admin/posts/:id/comments
+  def comments
+    @comments = resource.comments
+    # 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 Arbo file extension: .arb.
+
+For example, create `app/views/admin/posts/comments.html.arb` with:
+
+```ruby
+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 translated 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
+defaults to the name of the controller action.
+
+If this doesn't work for you, you can always set the `@page_title` instance
+variable in your controller action to customize the page title.
+
+```ruby
+class Admin::PostsController < ActiveAdmin::ResourceController
+  def comments
+    @comments   = resource.comments
+    @page_title = "#{resource.title}: Comments" # Sets the page title
+  end
+end
+```
+Alternately use `content_for(:page_title)` in the view template.
+
+# Action Items
+
+By default action items (like the New, Edit and Delete buttons) are rendered in
+a partial included in the right hand side of the title bar.
+
+For example, to add a "View on site" button to view a blog post customize the `action_item` partial as follows:
+
+```ruby
+# app/views/admin/posts/_action_item.html.arb
+div(class: :action_items) do
+  if params[:action] == 'index'
+    if controller.action_methods.include?('new') && authorized?(:create, Post)
+      action_link :new_model, new_resource_path
+    end
+  end
+
+  if params[:action] == 'show'
+    if controller.action_methods.include?('edit') && authorized?(:update, resource)
+      action_link :edit_model, edit_resource_path(resource)
+    end
+
+    if resource.published? && current_admin_user.super_admin?
+      action_link "View on site", post_path(resource)
+    end
+  end
+end
+```
+
+# Modifying the Controller
+
+Using the `controller` method within the registration block is deprecated, create and modify the controller explicitly.