# ActiveScaffold Batch

ActiveScaffold Batch adds actions for creating, updating, and deleting multiple records from an ActiveScaffold list.

## Requirements

The upcoming 3.8 release requires ActiveScaffold 4.4 or newer. Use ActiveScaffold Batch 3.7.x with older ActiveScaffold releases.

## Installation

Add the gem to your `Gemfile`:

```ruby
gem 'active_scaffold_batch'
```

Then run `bundle install`.

## Enable actions

Enable only the actions an application needs:

```ruby
class UsersController < ApplicationController
  active_scaffold :user do |config|
    config.actions.add :batch_update
    config.actions.add :batch_destroy
  end
end
```

The plugin provides `batch_create`, `batch_update`, and `batch_destroy`. Batch Update and Batch Destroy can operate on every record in the current filtered list. When the `mark` action is enabled, they can also operate only on marked records.

## Batch Create

Batch Create has two distinct modes.

With no `default_batch_by_column`, it is a multiple-row create form. It initially displays one new record and lets the user add more blank rows before submitting them together:

```ruby
config.actions.add :batch_create
config.batch_create.layout = :vertical # or :horizontal
```

With `default_batch_by_column`, one form is applied once for every selected value of that column. For example, the following configuration creates one player for each selected team while sharing the other entered player attributes:

```ruby
config.actions.add :batch_create
config.batch_create.default_batch_by_column = :team
```

The batch column may be a `belongs_to` association or a scalar column. For a scalar column, enter one value per line.

By default, Batch Create validates and saves all records in one transaction and rolls everything back when any record fails. The supported settings are:

```ruby
config.batch_create.run_in_transaction = true
config.batch_create.layout = :vertical
config.batch_create.list_mode_enabled = true
```

Set `run_in_transaction` to `false` to retain successful records when another row fails, or to `:validate_first` to validate every record before saving any of them.

## Batch Update

Batch Update presents an operator for each editable column. `NO_UPDATE` leaves the column unchanged and `REPLACE` assigns the entered value. Numeric columns also support addition, subtraction, multiplication, and division with absolute or percentage operands. Date columns support addition and subtraction.

```ruby
config.actions.add :batch_update
config.batch_update.list_mode_enabled = true
config.batch_update.process_mode = :update
```

The default `:update` mode instantiates every record and runs authorization, validations, and callbacks. `:update_all` performs direct SQL updates and skips those model callbacks and validations.

## Batch Destroy

```ruby
config.actions.add :batch_destroy
config.batch_destroy.process_mode = :delete
```

The default `:delete` mode processes records individually through ActiveScaffold. `:delete_all` uses direct SQL and skips model callbacks. Both modes expose separate links for the current filtered list and, when marking is enabled, marked records.

## UI adapter support

Version 3.8 reuses ActiveScaffold 4.4's standard form elements. Refer to ActiveScaffold's UI element reference for `form`, `form_title`, `fields_container`, `form_element`, `form_attribute`, `form_control`, form footer controls, and the other shared elements.

Batch defines only one plugin-specific element:

| Element | Type | Used for |
|---|---|---|
| `batch_create_add_rows` | Attributes only | Remote link that adds blank rows to a multiple-row Batch Create form. |

For example, an adapter can customize the Batch-specific add-row link without replacing its template:

```ruby
ActiveScaffold.add_element_attributes :batch_create_add_rows,
                                      class: 'btn btn-sm btn-secondary'
```

Batch-specific inputs use the shared `form_control` element. Its proc receives the usual `column` and `form_ui` context plus `batch_role`, which identifies `batch_scope`, `batch_update_operator`, `batch_update_value`, `batch_update_numeric_option`, `batch_update_date_amount`, `batch_update_date_unit`, or `batch_create_row_count`. This lets an adapter distinguish the controls when necessary without adding a separate registry element for each one.

The shared elements use the same definitions as ActiveScaffold's ordinary forms, so one adapter configuration keeps core and Batch forms consistent.

## Safety

List-scoped actions affect the complete filtered result, not only the visible page. Prefer marked-record scope for destructive operations when the user should explicitly select every affected record. Use the per-record processing modes when callbacks, validations, or authorization checks are required.