9-batch-actions.md in yousty-activeadmin-1.0.5.pre

- old
+ new
@@ -1,155 +1,233 @@
-# Index Batch Actions
+# 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.  If you override the default index, `selectable_column` must be used as the first column to enable 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:
 
-    index do
-      selectable_column
-      # add other columns here...
+```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|
+    Post.find(ids).each do |post|
+      post.flag! :hot
     end
+    redirect_to collection_path, alert: "The posts have been flagged."
+  end
+end
+```
 
-## Provided Batch Action
+### Disabling Batch Actions
 
-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).
+You can disable batch actions at the application, namespace, or resource level:
 
-## Creating Your Own Batch Actions
+```ruby
+# config/initializers/active_admin.rb
+ActiveAdmin.setup do |config|
 
-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.
+  # Application level:
+  config.batch_actions = false
 
-    ActiveAdmin.register Post do
-      batch_action :flag do |selection|
-        Post.find(selection).each do |post|
-          post.flag! :hot
-        end
-        redirect_to collection_path, :alert => "The posts have been flagged."
-      end
-    end
+  # Namespace level:
+  config.namespace :admin do |admin|
+    admin.batch_actions = false
+  end
+end
 
-### Disabling Batch Actions
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  
+  # Resource level:
+  config.batch_actions = false
+end
+```
 
-You can disable batch actions at the application or namespace level in
-`config/initializers/active_admin.rb`:
+### Modification
 
-    ActiveAdmin.setup do |config|
+If you want, you can override the default batch action to do whatever you want:
 
-      # Disable all batch actions
-      config.batch_actions = false
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy do |ids|
+    redirect_to collection_path, alert: "Didn't really delete these!"
+  end
+end
+```
 
+### Removal
 
-      # Or disable for a given namespace
-      config.namespace :admin do |admin|
-        admin.batch_actions = false
-      end
-    end
+You can remove batch actions by simply passing false as the second parameter:
 
-You can disable batch actions on any given resource using:
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy, false
+end
+```
 
-    ActiveAdmin.register Post do
-      config.batch_actions = 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.
 
-### Modifying a Previously Registered Batch Action
+```ruby
+ActiveAdmin.register Post do
+  batch_action :flag, if: proc{ can? :flag, Post } do |ids|
+    # ...
+  end
+end
+```
 
-If you wanted to modify the behavior of the provided "Delete" batch action, you can override by:
+### Priority in the drop-down menu
 
-    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
+You can change the order of batch actions through the `:priority` option:
 
-### Removing a Batch Action
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy, priority: 1 do |ids|
+    # ...
+  end
+end
+```
 
-You can also remove batch actions by simply passing false as the second parameter:
+### Confirmation prompt
 
-    ActiveAdmin.register Post do
-      batch_action :destroy, false
-    end
+You can pass a custom string to prompt the user with:
 
-### Conditional Display of Batch Action
+```ruby
+ActiveAdmin.register Post do
+  batch_action :destroy, confirm: "Are you sure??" do |ids|
+    # ...
+  end
+end
+```
 
-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.
+### Batch Action forms
 
-    ActiveAdmin.register Post do
-      batch_action :flag, :if => proc { false } do |selection|
-        # This action won't ever be displayed
-      end
-    end
+If you want to capture input from the user as they perform a batch action,
+Active Admin has just the thing for you:
 
-### Batch Action Priority in Menu
+```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
+```
 
-You can also change the order of batch actions, by providing a value for the :priority param:
+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.
 
-    ActiveAdmin.register Post do
-      batch_action :destroy, :priority => 1 do |selection|
-        # Do some deleting in here...
-      end
-    end
+```ruby
+batch_action :doit, form: {user: [['Jake',2], ['Mary',3]]} do |ids, inputs|
+  User.find(inputs[:user])
+  # ...
+end
+```
 
-### Batch Action I18n of Labels
+When you have dynamic form inputs you can pass a proc instead:
 
-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:
+```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
+```
 
-    ActiveAdmin.register Post do
-      batch_action :publish do |selection|
-        # do some publishing...
-      end
-    end
+Under the covers this is powered by the JS `ActiveAdmin.modal_dialog` which you can use yourself:
 
-Can be translated with:
+```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()
+```
 
-    # config/locales/en.yml
-    en:
-      active_admin:
-        batch_actions:
-          labels:
-            publish: "Publish"
+### Translation
 
-### Batch Action Confirmation
+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}`.
 
-You can also request that the user confirm the action, before the action is performed:
+So this:
 
-    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
+```ruby
+ActiveAdmin.register Post do
+  batch_action :publish do |ids|
+    # ...
+  end
+end
+```
 
-### Support for Other Index Types
+Can be translated with:
 
-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.
+```yaml
+# config/locales/en.yml
+en:
+  active_admin:
+    batch_actions:
+      labels:
+        publish: "Publish"
+```
 
-    ActiveAdmin.register Post do
+### Support for other index types
 
-      # By default, the "Delete" batch action is provided
+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.
 
-      # Index as Grid
-      index as: :grid do |post|
-        resource_selection_cell post
-        h2 auto_link( post )
-      end
+```ruby
+ActiveAdmin.register Post do
 
-      # Index as Blog requires nothing special
+  # By default, the "Delete" batch action is provided
 
-      # Index as Block
-      index as: :block do |post|
-        div for: post do
-          resource_selection_cell post
-        end
-      end
+  # 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
 
-### Batch Actions and Custom Actions 
+end
+```
 
-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.
+### BTW
 
-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. 
+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.
 
-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.
+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 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.