---

name: rails-form-objects description: Create Form Objects for complex form handling, multi-model forms, and validation logic. Use when forms involve multiple models, complex validations, or require business logic beyond simple CRUD operations.

Rails Form Objects Specialist

Specialized in implementing Form Objects pattern for complex form handling.

When to Use This Skill

• Multi-model forms (e.g., user registration with profile and settings)
• Complex validation logic beyond model validations
• Forms requiring business logic or side effects
• Virtual attributes not directly mapped to database columns
• Forms with conditional validations

Core Principles

• ActiveModel Integration: Include ActiveModel::Model for validation support
• Single Responsibility: Each form handles one specific form submission
• Composition: Coordinate multiple models
• Validation: Centralize form-specific validation logic
• Testability: Easy to test independently

Implementation Guidelines

Basic Form Object

# app/forms/user_registration_form.rb
class UserRegistrationForm
    include ActiveModel::Model

    attr_accessor :email, :password, :password_confirmation, :terms_accepted
    attr_accessor :profile_name, :profile_bio

    validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
    validates :password, length: { minimum: 8 }
    validates :password_confirmation, presence: true
    validates :terms_accepted, acceptance: true
    validates :profile_name, presence: true

    # WHY: Ensure password and confirmation match before processing
    validate :passwords_match

    def save
        return false unless valid?

        ActiveRecord::Base.transaction do
            user = create_user
            create_profile(user)
            send_welcome_email(user)
            user
        end
    rescue ActiveRecord::RecordInvalid => e
        # WHY: Add model errors to form object for unified error handling
        errors.add(:base, e.message)
        false
    end

    private

    def passwords_match
        if password != password_confirmation
            errors.add(:password_confirmation, "doesn't match password")
        end
    end

    def create_user
        User.create!(
            email: email,
            password: password
        )
    end

    def create_profile(user)
        UserProfile.create!(
            user: user,
            name: profile_name,
            bio: profile_bio
        )
    end

    def send_welcome_email(user)
        WelcomeMailer.welcome_email(user).deliver_later
    end
end

Controller Integration

# app/controllers/registrations_controller.rb
class RegistrationsController < ApplicationController
    def create
        @form = UserRegistrationForm.new(registration_params)

        if @form.save
            redirect_to dashboard_path, notice: 'Registration successful'
        else
            render :new
        end
    end

    private

    def registration_params
        params.require(:user_registration).permit(
            :email, :password, :password_confirmation,
            :terms_accepted, :profile_name, :profile_bio
        )
    end
end

View Integration

<!-- app/views/registrations/new.html.erb -->
<%= form_with model: @form, url: registrations_path, local: true do |f| %>
  <%= f.label :email %>
  <%= f.email_field :email %>
  <%= f.error_messages_for :email %>

  <%= f.label :password %>
  <%= f.password_field :password %>
  <%= f.error_messages_for :password %>

  <%= f.label :profile_name %>
  <%= f.text_field :profile_name %>
  <%= f.error_messages_for :profile_name %>

  <%= f.check_box :terms_accepted %>
  <%= f.label :terms_accepted, "I accept the terms" %>
  <%= f.error_messages_for :terms_accepted %>

  <%= f.submit "Register" %>
<% end %>

Tools to Use

• Read: Read existing form objects and related models
• Write: Create new form object files
• Edit: Modify existing form objects
• Bash: Run tests for form objects
• mcp__serena__find_symbol: Find related models and validators

Bash Commands

# Create forms directory
mkdir -p app/forms

# Run form object tests
bundle exec rspec spec/forms/user_registration_form_spec.rb

Workflow

1. Identify Complex Form: Determine if form needs Form Object pattern
2. Write Tests First: Use rails-rspec-testing skill
3. Define Attributes: Declare all form attributes with attr_accessor
4. Add Validations: Implement form-specific validations
5. Implement Save Method: Coordinate model creation/updates
6. Handle Errors: Propagate errors to form object
7. Test: Ensure all tests pass

Related Skills

• rails-rspec-testing: For writing form object tests
• rails-model-design: For understanding model interfaces
• rails-transactions: For transaction coordination
• rails-service-objects: For complex business logic within forms

Coding Standards

See Rails Coding Standards

TDD Workflow

Follow TDD Workflow

Key Reminders

• Include ActiveModel::Model for validation support
• Use transactions for multi-model operations
• Propagate model errors to form object
• Keep form logic separate from models
• Test form objects independently
• Use strong parameters in controllers