Form Object Patterns for Rails 8

Overview

Form objects encapsulate complex form logic:

• Multi-model forms (user + profile + address)
• Search/filter forms (non-persisted)
• Wizard/multi-step forms
• Virtual attributes with validation
• Decoupled from ActiveRecord models

When to Use Form Objects

Scenario	Use Form Object?
Single model CRUD	No (use model)
Multi-model creation	Yes
Complex validations across models	Yes
Search/filter forms	Yes
Wizard/multi-step forms	Yes
API params transformation	Yes
Contact forms (no persistence)	Yes

TDD Workflow

Form Object Progress:
- [ ] Step 1: Define form requirements
- [ ] Step 2: Write form object spec (RED)
- [ ] Step 3: Run spec (fails)
- [ ] Step 4: Create form object
- [ ] Step 5: Run spec (GREEN)
- [ ] Step 6: Wire up controller
- [ ] Step 7: Create view form

Project Structure

app/
├── forms/
│   ├── application_form.rb       # Base class
│   ├── registration_form.rb      # Multi-model
│   ├── search_form.rb            # Non-persisted
│   └── wizard/
│       ├── base_form.rb
│       ├── step_one_form.rb
│       └── step_two_form.rb
spec/forms/
├── registration_form_spec.rb
└── search_form_spec.rb

Base Form Class

# app/forms/application_form.rb
class ApplicationForm
  include ActiveModel::Model
  include ActiveModel::Attributes
  include ActiveModel::Validations

  def self.model_name
    ActiveModel::Name.new(self, nil, name.chomp("Form"))
  end

  def persisted?
    false
  end

  def save
    return false unless valid?
    persist!
    true
  rescue ActiveRecord::RecordInvalid => e
    errors.add(:base, e.message)
    false
  end

  private

  def persist!
    raise NotImplementedError
  end
end

Patterns

Four patterns are implemented with full TDD cycles. See patterns.md:

• Pattern 1: Multi-Model Registration Form — creates a User and Account in a transaction; validates email uniqueness and password confirmation; exposes form.user and form.account after save. Includes spec (RED) and implementation (GREEN).
• Pattern 2: Search/Filter Form — non-persisted form with query, type, status, and date range filters applied as chainable scopes; exposes results and any_filters? helpers for views. Includes spec and implementation.
• Pattern 3: Wizard/Multi-Step Form — Wizard::BaseForm provides next_step, previous_step, first_step?, last_step?, and progress_percentage; each step subclass declares its own attributes and validations.
• Pattern 4: Contact Form (No Persistence) — overrides #save directly (no persist!); dispatches via deliver_later without writing to the database.

Controller and View Integration

See controller-and-views.md for:

• Standard controller with allow_unauthenticated_access, #new / #create, render :new, status: :unprocessable_entity on failure
• form_with model: @form views with error display
• Search form partial with selects, date fields, and a "Clear" link when filters are active

Key conventions:

• Use form_with model: @form, url: explicit_path — the form object is not an ActiveRecord model
• Permit params with params.require(:model_name).permit(...) using the snake-case class name without "Form"
• Always render :new, status: :unprocessable_entity on failure so Turbo handles the response

Checklist

• Spec written first (RED)
• Extends ApplicationForm or includes ActiveModel::Model
• Attributes declared with types
• Validations defined
• #save method with transaction (if multi-model)
• Controller uses form object
• View uses form_with model: @form
• Error handling in place
• All specs GREEN

References

• patterns.md — Full TDD implementations of all 4 patterns: multi-model registration, search/filter, wizard/multi-step, and contact form
• controller-and-views.md — Controller with unauthenticated access, registration form view, and search form partial