activeadmin 0.6.6 → 1.0.0.pre1

data/docs/6-show-pages.md

@@ -1,43 +1,105 @@
 # Customize the Show Page
 
-Customize the show page is as simple as implementing the show block:
+The show block is rendered within the context of the view and uses [Arbre](https://github.com/activeadmin/arbre) syntax.
 
-    ActiveAdmin.register Post do
-      show do
-        h3 post.title
-        div do
-          simple_format post.body
-        end
-      end
+With the `show` block, you can render anything you want.
+
+```ruby
+ActiveAdmin.register Post do
+  show do
+    h3 post.title
+    div do
+      simple_format post.body
     end
+  end
+end
+```
+
+You can render a partial at any point:
+
+```ruby
+ActiveAdmin.register Post do
+  show do
+    # renders app/views/admin/posts/_some_partial.html.erb
+    render 'some_partial'
+  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.
+If you'd like to keep the default AA look, you can use `attributes_table`:
 
-    ActiveAdmin.register Post do
-      show do
-        # renders app/views/admin/posts/_some_partial.html.erb
-        render "some_partial"
+```ruby
+ActiveAdmin.register Ad do
+  show do
+    attributes_table do
+      row :title
+      row :image do |ad|
+        image_tag ad.image.url
       end
     end
+    active_admin_comments
+  end
+end
+```
 
-If you'd like to keep the default active_admin look, you can also use "attributes_table":
+You can also customize the title of the object in the show screen:
 
-    ActiveAdmin.register Ad do
-      show do |ad|
-        attributes_table do
-          row :title
-          row :image do
-            image_tag(ad.image.url)
-          end
-        end
-        active_admin_comments
+```ruby
+show title: :name do
+  # ...
+end
+```
+
+If you want a more data-dense page, you can combine a sidebar:
+
+```ruby
+ActiveAdmin.register Book do
+  show do
+    panel "Table of Contents" do
+      table_for book.chapters do
+        column :number
+        column :title
+        column :page
       end
     end
+    active_admin_comments
+  end
 
-You can customize the title of the object in the show screen.  The default is the resource name and the ID.  You can customize as follows:
-
-    show :title => :name 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
+```
+
+# Tabs
 
+You can arrage content in tabs as shown below:
 
+```ruby
+  ActiveAdmin.register Order do 
+    show do
+      tabs do
+        tab 'Overview' do
+          attributes_table do
+            row(:status) { status_tag(order.status) }
+            row(:paid) { number_to_currency(order.amount_paid_in_dollars) }
+          end
+        end
+        
+        tab 'Payments' do
+          table_for order.payments do
+            column('Payment Type') { |p| p.payment_type.titleize }
+            column('Received On', :created_at)
+            column('Payment Details & Notes', :notes)
+            column('Amount') { |p| number_to_currency(p.amount_in_dollars) }
+          end
+        end
+      end
+    end
+  end
+```

data/docs/7-sidebars.md

@@ -1,42 +1,63 @@
 # Sidebar Sections
 
-To add a sidebar section to all the screen within a section, use the sidebar method:
+Sidebars allow you to put whatever content you want on the side the page.
 
-    sidebar :help do
-      "Need help? Email us at help@example.com"
-    end
+```ruby
+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.
+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.
 
-You can also use Arbre syntax to define the content.
+You can also use [Arbre](https://github.com/activeadmin/arbre) to define HTML content.
 
-    sidebar :help do
-      ul do
-        li "Second List First Item"
-        li "Second List Second Item"
-      end
-    end
+```ruby
+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.
+Sidebars can be rendered on a specific action by passing `:only` or `:except`.
 
-    sidebar :help, :only => :index do
-      "Need help? Email us at help@example.com"
-    end
+```ruby
+sidebar :help, only: :index do
+  "Need help? Email us at help@example.com"
+end
+```
 
 If you want to conditionally display a sidebar section, use the :if option and
-pass it a proc which will be rendered within the context of the view.
+pass it a proc which will be rendered within the view context.
 
-    sidebar :help, :if => proc{ current_admin_user.super_admin? }
-      "Only for super admins!"
-    end
+```ruby
+sidebar :help, if: proc{ current_admin_user.super_admin? } do
+  "Only for super admins!"
+end
+```
 
-If you only pass a symbol, Active Admin will attempt to locate a partial to render.
+You can also render a partial:
 
-    # Will render app/views/admin/posts/_help_sidebar.html.erb
-    sidebar :help
+```ruby
+sidebar :help                    # app/views/admin/posts/_help_sidebar.html.erb
+sidebar :help, partial: 'custom' # app/views/admin/posts/_custom.html.erb
+```
 
-Or you can pass your own custom partial to render.
+It's possible to add custom class name to the sidebar parent element by passing
+`class` option:
 
-    sidebar :help, :partial => "custom_help_partial"
+```ruby
+sidebar :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
+sidebar :help, priority: 0 # will push Help section to the top (above default Filters section)
+```
+
+Default sidebar priority is `10`.

data/docs/8-custom-actions.md

@@ -12,18 +12,19 @@ generating a route for you.
 
 To add a collection action, use the collection_action method:
 
+```ruby
+ActiveAdmin.register Post do
 
-    ActiveAdmin.register Post do
+  collection_action :import_csv, method: :post do
+    # Do some CSV importing work here...
+    redirect_to collection_path, notice: "CSV imported successfully!"
+  end
 
-      collection_action :import_csv, :method => :post do
-        # Do some CSV importing work here...
-        redirect_to {:action => :index}, {:notice => "CSV imported successfully!"}
-      end
+end
+```
 
-    end
-
-This collection action will generate a route at "/admin/posts/import_csv"
-pointing to the Admin::PostsController#import_csv controller action.
+This collection action will generate a route at `/admin/posts/import_csv`
+pointing to the `Admin::PostsController#import_csv` controller action.
 
 ## Member Actions
 
@@ -32,108 +33,128 @@ 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
+```ruby
+ActiveAdmin.register User do
 
-      member_action :lock, :method => :put do
-        user = User.find(params[:id])
-        user.lock!
-        redirect_to {:action => :show}, {:notice => "Locked!"}
-      end
+  member_action :lock, method: :put do
+    resource.lock!
+    redirect_to resource_path, notice: "Locked!"
+  end
 
-    end
+end
+```
 
-This will generate a route at "/admin/users/:id/lock" pointing to the
-Admin::UserController#lock controller action.
+This will generate a route at `/admin/users/:id/lock` pointing to the
+`Admin::UserController#lock` controller action.
 
-## Controller Action HTTP Verb
+## HTTP Verbs
 
-The collection_action and member_actions methods both accept the "method"
+The `collection_action` and `member_action` 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.
+Sometimes you want to create an action with the same name, that handles multiple
+HTTP verbs. In that case, this is the suggested approach:
 
-## Rendering in Custom Actions
+```ruby
+member_action :foo, method: [:get, :post] do
+  if request.post?
+    resource.update_attributes! foo: params[:foo] || {}
+    head :ok
+  else
+    render :foo
+  end
+end
+```
+
+## Rendering
 
 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])
+```ruby
+ActiveAdmin.register Post do
 
-        # This will render app/views/admin/posts/comments.html.erb
-      end
+  # /admin/posts/:id/comments
+  member_action :comments do
+    @comments = resource.comments
+    # This will render app/views/admin/posts/comments.html.erb
+  end
 
-    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
+For example, create `app/views/admin/posts/comments.html.arb` with:
 
-### Custom Action Items
+```ruby
+table_for assigns[:post].comments do
+  column :id
+  column :author
+  column :body do |comment|
+    simple_format comment.body
+  end
+end
+```
 
-To include your own action items (like the New, Edit and Delete buttons), add an
-`action_item` block. For example, to add a "View on site" button to view a blog
-post:
+## Page Titles
 
-    action_item :only => :show do
-      link_to('View on site', post_path(post)) if post.published?
-    end
+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.
 
-Actions items also accept the :if option to conditionally display them:
+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.
 
-    action_item :only => :show, :if => proc{ current_admin_user.super_admin? } do
-      "Only display this to super admins on the show screen"
-    end
+```ruby
+ActiveAdmin.register Post do
 
-### Page Titles
+  member_action :comments do
+    @comments   = resource.comments
+    @page_title = "#{resource.title}: Comments" # Sets the page title
+  end
 
-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.
+end
+```
 
-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.
+# Action Items
 
-    ActiveAdmin.register Post do
+To include your own action items (like the New, Edit and Delete buttons), add an
+`action_item` block. The first parameter is just a name to identify the action,
+and is required. For example, to add a "View on site" button to view a blog
+post:
 
-      # /admin/posts/:id/comments
-      member_action :comments do
-        @post = Post.find(params[:id])
-        @page_title = "#{@post.title}: Comments" # Set the page title
+```ruby
+action_item :view, only: :show do
+  link_to 'View on site', post_path(post) if post.published?
+end
+```
 
-        # This will render app/views/admin/posts/comments.html.erb
-      end
+Actions items also accept the `:if` option to conditionally display them:
 
-    end
+```ruby
+action_item :super_action, only: :show, if: proc{ current_admin_user.super_admin? } do
+  "Only display this to super admins on the show screen"
+end
+```
 
-## Modify the Controller
+# Modifying the Controller
 
 The generated controller is available to you within the registration block by
-using the #controller method.
+using the `controller` method.
 
-    ActiveAdmin.register Post do
+```ruby
+ActiveAdmin.register Post do
 
-      controller do
-        # This code is evaluated within the controller class
-
-        def define_a_method
-          # Instance method
-        end
-      end
+  controller do
+    # This code is evaluated within the controller class
 
+    def define_a_method
+      # Instance method
     end
+  end
+
+end
+```

data/docs/9-batch-actions.md

@@ -1,169 +1,233 @@
-# Index Batch Actions
-
-By default, the index view includes a way to quickly delete records from the listing,
-as well as an API for you to easily create your own "Batch Action" for handling a request to operate
-on multiple records at once.
-
-## Provided Batch Action
-
-The `batch_action` API provides one default batch action for use in your application immediately, for deleting
-multiple records at once.  You are able to disable this action if you desire (see below).
-
-## Creating Your Own Batch Actions
-
-To create your own batch action, use the `batch_action` method.  You are provided an array of record IDs
-to operate on.  The array should contain at least one ID.
-
-    ActiveAdmin.register Post do
-      batch_action :flag do |selection|
-        Post.find(selection).each do |post|
-          post.flag! :hot
-        end
-      end
+# Batch Actions
+
+By default, the index page provides you a "Batch Action" to quickly delete records,
+as well as an API for you to easily create your own. Note that if you override the
+default index, you must add `selectable_column` back for batch actions to be usable:
+
+```ruby
+index do
+  selectable_column
+  # ...
+end
+```
+
+## Creating your own
+
+Use the `batch_action` DSL method to create your own. It behaves just like a
+controller method, so you can send the client whatever data you like. Your block
+is passed an array of the record IDs that the user selected, so you can perform
+your desired batch action on all of them:
+
+```ruby
+ActiveAdmin.register Post do
+  batch_action :flag do |ids|
+    batch_action_collection.find(ids).each do |post|
+      post.flag! :hot
     end
+    redirect_to collection_path, alert: "The posts have been flagged."
+  end
+end
+```
 
 ### Disabling Batch Actions
 
-You can disable batch actions at the application or namespace level in
-`config/initializers/active_admin.rb`:
-
-    ActiveAdmin.setup do |config|
-
-      # Disable all batch actions
-      config.batch_actions = false
-
-
-      # Or disable for a given namespace
-      config.namespace :admin do |admin|
-        admin.batch_actions = false
-      end
-    end
-
-You can disable batch actions on any given resource using:
-
-    ActiveAdmin.register Post do
-      config.batch_actions = false
-    end
-
-
-### Modifying a Previously Registered Batch Action
-
-If you wanted to modify the behavior of the provided "Delete" batch action, you can override by:
-
-    ActiveAdmin.register Post do
-      batch_action :destroy, :if => proc { can?( :destroy, Post ) } do |selection|
-        redirect_to collection_path, :alert => "Didn't really delete these!"
-      end
-    end
-
-### Removing a Batch Action
-
-You can also remove batch actions by simply passing false as the second parameter:
-
-    ActiveAdmin.register Post do
-      batch_action :destroy, false
-    end
-
-### Conditional Display of Batch Action
-
-You can control whether or not the batch action is available via the `:if` option. Provide a boolean or a proc, which is executed in context of the view.
-
-    ActiveAdmin.register Post do
-      batch_action :flag, :if => proc { false } do |selection|
-        # This action won't ever be displayed
-      end
-    end
-
-### Batch Action Priority in Menu
-
-You can also change the order of batch actions, by providing a value for the :priority param:
-
-    ActiveAdmin.register Post do
-      batch_action :destroy, :priority => 1 do |selection|
-        # Do some deleting in here...
-      end
-    end
-
-### Batch Action I18n of Labels
+You can disable batch actions at the application, namespace, or resource level:
+
+```ruby
+# config/initializers/active_admin.rb
+ActiveAdmin.setup do |config|
+
+  # Application level:
+  config.batch_actions = false
+
+  # Namespace level:
+  config.namespace :admin do |admin|
+    admin.batch_actions = false
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  
+  # Resource level:
+  config.batch_actions = false
+end
+```
+
+### Modification
+
+If you want, you can override the default batch action to do whatever you want:
+
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy do |ids|
+    redirect_to collection_path, alert: "Didn't really delete these!"
+  end
+end
+```
+
+### Removal
+
+You can remove batch actions by simply passing false as the second parameter:
+
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy, false
+end
+```
+
+### Conditional display
+
+You can control whether or not the batch action is available via the `:if`
+option, which is executed in the view context.
+
+```ruby
+ActiveAdmin.register Post do
+  batch_action :flag, if: proc{ can? :flag, Post } do |ids|
+    # ...
+  end
+end
+```
+
+### Priority in the drop-down menu
+
+You can change the order of batch actions through the `:priority` option:
+
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy, priority: 1 do |ids|
+    # ...
+  end
+end
+```
+
+### Confirmation prompt
+
+You can pass a custom string to prompt the user with:
+
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy, confirm: "Are you sure??" do |ids|
+    # ...
+  end
+end
+```
+
+### Batch Action forms
+
+If you want to capture input from the user as they perform a batch action,
+Active Admin has just the thing for you:
+
+```ruby
+batch_action :flag, form: {
+  type: %w[Offensive Spam Other],
+  reason: :text,
+  notes:  :textarea,
+  hide:   :checkbox,
+  date:   :datepicker
+} do |ids, inputs|
+  # inputs is a hash of all the form fields you requested
+  redirect_to collection_path, notice: [ids, inputs].to_s
+end
+```
+
+If you pass a nested array, it will behave just like Formtastic would, with the first
+element being the text displayed and the second element being the value.
+
+```ruby
+batch_action :doit, form: {user: [['Jake',2], ['Mary',3]]} do |ids, inputs|
+  User.find(inputs[:user])
+  # ...
+end
+```
+
+When you have dynamic form inputs you can pass a proc instead:
+
+```ruby
+# NOTE: multi-pluck is new to Rails 4
+batch_action :doit, form: ->{{user: User.pluck(:name, :id)}} do |ids, inputs|
+  User.find(inputs[:user])
+  # ...
+end
+```
+
+Under the covers this is powered by the JS `ActiveAdmin.modal_dialog` which you can use yourself:
+
+```coffee
+if $('body.admin_users').length
+  $('a[data-prompt]').click ->
+    ActiveAdmin.modal_dialog $(@).data('prompt'), comment: 'textarea',
+      (inputs)=>
+        $.post "/admin/users/#{$(@).data 'id'}/change_state",
+          comment: inputs.comment, state: $(@).data('state'),
+          success: ->
+            window.location.reload()
+```
+
+### Translation
 
 By default, the name of the batch action will be used to lookup a label for the
-menu. It will lookup in `active_admin.batch_actions.labels.#{your_batch_action_name}`. For
-example:
+menu. It will lookup in `active_admin.batch_actions.labels.#{your_batch_action}`.
 
-    ActiveAdmin.register Post do
-      batch_action :publish do |selection|
-        # do some publishing...
-      end
-    end
-
-Can be translated with:
+So this:
 
-    # config/locales/en.yml
-    en:
-      active_admin:
-        batch_actions:
-          labels:
-            publish: "Publish"
+```ruby
+ActiveAdmin.register Post do
+  batch_action :publish do |ids|
+    # ...
+  end
+end
+```
 
-### Batch Action Confirmation
+Can be translated with:
 
-You can also request that the user confirm the action, before the action is performed:
+```yaml
+# config/locales/en.yml
+en:
+  active_admin:
+    batch_actions:
+      labels:
+        publish: "Publish"
+```
 
-    ActiveAdmin.register Post do
-      batch_action :destroy, :confirm => "Are you sure you want to delete all of these?" do |selection|
-        # Do some deleting...
-      end
-    end
+### Support for other index types
 
-### Customizing Table Columns
+You can easily use `batch_action` in the other index views, *Grid*, *Block*,
+and *Blog*; however, these will require custom styling to fit your needs.
 
-To include the column with checkboxes in after overriding the list of columns for the `index` block in the *Table* listing, use the following helper as seen below:
+```ruby
+ActiveAdmin.register Post do
 
-    ActiveAdmin.register Post do
+  # By default, the "Delete" batch action is provided
 
-      batch_action :flag do |selection|
-        Post.find(selection).each { |p| p.flag! }
-        redirect_to collection_path, :notice => "Posts flagged!"
-      end
+  # Index as Grid
+  index as: :grid do |post|
+    resource_selection_cell post
+    h2 auto_link post
+  end
 
-      index do
-        selectable_column
-        column :title
-        default_actions
-      end
+  # Index as Blog requires nothing special
 
+  # Index as Block
+  index as: :block do |post|
+    div for: post do
+      resource_selection_cell post
     end
+  end
 
+end
+```
 
-### Support for Other Index Types
-
-You can easily use `batch_action` in the other index views, *Grid*, *Block*, and *Blog*; however, these views will require more custom styling to fit your application needs.
-
-    ActiveAdmin.register Post do
-
-      # By default, the "Delete" batch action is provided
-
-      # Index as Grid
-      index as: :grid do |post|
-        resource_selection_cell post
-        h2 auto_link( post )
-      end
-
-      # Index as Blog requires nothing special
-
-      # Index as Block
-      index as: :block do |post|
-        div for: post do
-          resource_selection_cell post
-        end
-      end
-
-    end
-
-### Batch Actions and Custom Actions 
+### BTW
 
-In order to perform the batch action, the entire *Table*, *Grid*, etc. is wrapped in a form that submits the id's of the selected rows to your batch_action.
+In order to perform the batch action, the entire *Table*, *Grid*, etc. is
+wrapped in a form that submits the IDs of the selected rows to your batch_action.
 
-Since nested `<form>` tags in HTML often results in unexpected behavior, you may need to modify custom actions or forms you are using on your page with batch actions enabled. 
+Since nested `<form>` tags in HTML often results in unexpected behavior, you
+may need to modify the custom behavior you've built using to prevent conflicts.
 
-Specifically, if you are using HTTP methods like `PUT` or `PATCH` with a custom form on your index page this may result in your batch action being `PUT`ed instead of `POST`ed which in turn will create a routing error. You can get around this by either moving the nested form to another page (ie. the Object's show page) or, if possible, changing the method of the custom action to `POST` so that it doesn't override the batch action. Remember, behavior may vary by browser.
+Specifically, if you are using HTTP methods like `PUT` or `PATCH` with a custom
+form on your index page this may result in your batch action being `PUT`ed
+instead of `POST`ed which will create a routing error. You can get around this
+by either moving the nested form to another page or using a POST so it doesn't
+override the batch action. As well, behavior may vary by browser.