--- name: active-model description: Build plain Ruby objects that integrate with Rails forms, validations, serialization, and Action Pack — without a database. Use when building form objects, search forms, API wrappers, configuration objects, virtual models, or any PORO that needs model-like behavior. Triggers on "active model", "form object", "plain Ruby object", "non-database model", "ActiveModel", "PORO", "service object validation", "virtual model", "tableless model", "search form", "ActiveModel::API", "ActiveModel::Model". allowed-tools: Read, Grep, Glob, Write, Edit --- # Active Model Expert Build model-like Ruby classes that work with Rails forms, validations, and serialization — without touching a database. ## Core Decision: Active Model vs Active Record **Use Active Model when:** - No database table backs the object - Form objects that aggregate multiple models - Search/filter forms - API request/response wrappers - Configuration or settings objects - Contact forms, invite forms, onboarding wizards - Decorators or presenters needing validation - Service objects that need validation + error messages **Use Active Record when:** - Data must persist in a database - You need associations, scopes, or query interface - You need migrations and schema management **The #1 agent mistake:** Reaching for Active Record (or raw POROs with hand-rolled validation) when Active Model gives you everything Rails forms and controllers expect — for free. ## Module Hierarchy Understanding which module to include is critical: | Module | What You Get | When To Use | |--------|-------------|-------------| | `ActiveModel::Model` | API + future extensions | **Default choice** — use this | | `ActiveModel::API` | Validations, Naming, Conversion, Translation, AttributeAssignment | Lightweight alternative to Model | | `ActiveModel::Attributes` | Typed attributes with casting + defaults | Need type coercion (dates, booleans, integers) | | `ActiveModel::Validations` | Just validations | Adding validation to any object | | `ActiveModel::Callbacks` | Lifecycle hooks (before/after/around) | Need callback chains | | `ActiveModel::Dirty` | Change tracking | Track attribute modifications | | `ActiveModel::Serialization` | `serializable_hash` | Need hash/JSON output | | `ActiveModel::SecurePassword` | bcrypt password handling | Password without Active Record | **Key insight:** `ActiveModel::Model` includes `ActiveModel::API`, which bundles Validations, Naming, Conversion, Translation, and AttributeAssignment. Start with `Model` and add other modules as needed. ## Instructions ### Step 1: Choose the Right Base **For most form objects and virtual models — use `ActiveModel::Model`:** ```ruby class ContactForm include ActiveModel::Model attr_accessor :name, :email, :message validates :name, :email, :message, presence: true validates :email, format: { with: URI::MailTo::EMAIL_REGEXP } def submit return false unless valid? ContactMailer.new_message(name:, email:, message:).deliver_later true end end ``` This works with `form_with`, `render`, and all Action View helpers immediately. **When you need typed attributes — add `ActiveModel::Attributes`:** ```ruby class SearchForm include ActiveModel::Model include ActiveModel::Attributes attribute :query, :string attribute :min_price, :decimal attribute :max_price, :decimal attribute :available_only, :boolean, default: false attribute :created_after, :date validates :query, length: { minimum: 2 }, allow_blank: true def results scope = Product.all scope = scope.where("name ILIKE ?", "%#{query}%") if query.present? scope = scope.where("price >= ?", min_price) if min_price.present? scope = scope.where("price <= ?", max_price) if max_price.present? scope = scope.where(available: true) if available_only scope = scope.where("created_at >= ?", created_after) if created_after.present? scope end end ``` `Attributes` gives you automatic type casting — string `"true"` becomes boolean `true`, string `"2024-01-15"` becomes a `Date`. ### Step 2: Wire Into Controllers Active Model objects work exactly like Active Record in controllers: ```ruby class ContactFormsController < ApplicationController def new @contact_form = ContactForm.new end def create @contact_form = ContactForm.new(contact_form_params) if @contact_form.submit redirect_to root_path, notice: "Message sent!" else render :new, status: :unprocessable_entity end end private def contact_form_params params.require(:contact_form).permit(:name, :email, :message) end end ``` ### Step 3: Use with Forms ```erb <%= form_with model: @contact_form, url: contact_forms_path do |f| %> <% if @contact_form.errors.any? %>
<% @contact_form.errors.full_messages.each do |msg| %>

<%= msg %>

<% end %>
<% end %> <%= f.text_field :name %> <%= f.email_field :email %> <%= f.text_area :message %> <%= f.submit "Send" %> <% end %> ``` **Key:** You must provide `url:` in `form_with` since Active Model objects aren't routable by default (no `persisted?` returning true, no `id`). ### Step 4: Add Modules As Needed Only include what you actually use. Don't cargo-cult every module. **Callbacks** — when you need lifecycle hooks: ```ruby class RegistrationForm include ActiveModel::Model include ActiveModel::Attributes extend ActiveModel::Callbacks define_model_callbacks :save attribute :email, :string attribute :name, :string attribute :company_name, :string before_save :normalize_email after_save :send_welcome_email def save return false unless valid? run_callbacks(:save) do create_records! end true end private def normalize_email self.email = email.downcase.strip end def send_welcome_email WelcomeMailer.registration(@user).deliver_later end def create_records! @company = Company.create!(name: company_name) @user = @company.users.create!(email:, name:) end end ``` **Important:** `extend` (not `include`) for Callbacks. And you must call `run_callbacks(:event) { ... }` yourself — Active Model doesn't auto-invoke them. **Dirty tracking** — when you need change detection: ```ruby class Settings include ActiveModel::Model include ActiveModel::Dirty define_attribute_methods :theme, :language def theme @theme end def theme=(value) theme_will_change! unless value == @theme @theme = value end def language @language end def language=(value) language_will_change! unless value == @language @language = value end def save changes_applied end def reload! clear_changes_information end end ``` **Serialization** — for JSON APIs: ```ruby class ApiResponse include ActiveModel::Model include ActiveModel::Serializers::JSON attr_accessor :status, :data, :timestamp def attributes { "status" => nil, "data" => nil, "timestamp" => nil } end end response = ApiResponse.new(status: "ok", data: { count: 42 }, timestamp: Time.current) response.as_json # => {"status"=>"ok", "data"=>{"count"=>42}, "timestamp"=>"2024-..."} response.to_json # => '{"status":"ok",...}' ``` **SecurePassword** — password handling without Active Record: ```ruby class SessionForm include ActiveModel::Model include ActiveModel::SecurePassword has_secure_password attr_accessor :password_digest def authenticate_user(email, password) user = User.find_by(email:) user&.authenticate(password) end end ``` Requires the `bcrypt` gem. Provides `password`, `password_confirmation`, and `authenticate` methods. ### Step 5: Naming and Translation `ActiveModel::Model` includes Naming and Translation automatically. **Customize model name** (useful for namespaced classes): ```ruby module Admin class InviteForm include ActiveModel::Model def self.model_name ActiveModel::Name.new(self, nil, "InviteForm") end end end # Without override: form params would be admin_invite_form[email] # With override: form params are invite_form[email] ``` **I18n for attribute names:** ```yaml # config/locales/en.yml en: activemodel: attributes: contact_form: name: "Full Name" email: "Email Address" errors: models: contact_form: attributes: email: invalid: "doesn't look right" ``` ### Step 6: Test Active Model Objects ```ruby require "test_helper" class ContactFormTest < ActiveSupport::TestCase test "valid with all attributes" do form = ContactForm.new(name: "Jane", email: "jane@example.com", message: "Hello") assert form.valid? end test "invalid without name" do form = ContactForm.new(email: "jane@example.com", message: "Hello") refute form.valid? assert_includes form.errors[:name], "can't be blank" end test "invalid with bad email" do form = ContactForm.new(name: "Jane", email: "not-an-email", message: "Hello") refute form.valid? assert_includes form.errors[:email], "is invalid" end test "#submit delivers email when valid" do form = ContactForm.new(name: "Jane", email: "jane@example.com", message: "Hello") assert_enqueued_emails 1 do assert form.submit end end test "#submit returns false when invalid" do form = ContactForm.new refute form.submit end end ``` **Lint tests** — verify API compliance: ```ruby class ContactFormLintTest < ActiveSupport::TestCase include ActiveModel::Lint::Tests setup do @model = ContactForm.new end end ``` ## Common Patterns ### Form Object (Multi-Model) ```ruby class RegistrationForm include ActiveModel::Model include ActiveModel::Attributes attribute :user_email, :string attribute :user_name, :string attribute :company_name, :string attribute :plan, :string, default: "free" validates :user_email, :user_name, :company_name, presence: true validates :user_email, format: { with: URI::MailTo::EMAIL_REGEXP } validates :plan, inclusion: { in: %w[free pro enterprise] } def save return false unless valid? ActiveRecord::Base.transaction do company = Company.create!(name: company_name) company.users.create!(email: user_email, name: user_name) company.subscriptions.create!(plan:) end true rescue ActiveRecord::RecordInvalid => e errors.add(:base, e.message) false end end ``` ### Search/Filter Form ```ruby class OrderSearch include ActiveModel::Model include ActiveModel::Attributes attribute :status, :string attribute :customer_name, :string attribute :date_from, :date attribute :date_to, :date attribute :min_total, :decimal attribute :sort_by, :string, default: "created_at" attribute :sort_direction, :string, default: "desc" def results scope = Order.includes(:customer) scope = scope.where(status:) if status.present? scope = scope.joins(:customer).where("customers.name ILIKE ?", "%#{customer_name}%") if customer_name.present? scope = scope.where("orders.created_at >= ?", date_from) if date_from.present? scope = scope.where("orders.created_at <= ?", date_to) if date_to.present? scope = scope.where("orders.total >= ?", min_total) if min_total.present? scope = scope.order(sort_by => sort_direction) scope end end ``` ### Configuration Object ```ruby class NotificationPreferences include ActiveModel::Model include ActiveModel::Attributes include ActiveModel::Serializers::JSON attribute :email_enabled, :boolean, default: true attribute :sms_enabled, :boolean, default: false attribute :digest_frequency, :string, default: "daily" attribute :quiet_hours_start, :integer, default: 22 attribute :quiet_hours_end, :integer, default: 8 validates :digest_frequency, inclusion: { in: %w[realtime hourly daily weekly] } validates :quiet_hours_start, :quiet_hours_end, numericality: { in: 0..23 } def attributes { "email_enabled" => nil, "sms_enabled" => nil, "digest_frequency" => nil, "quiet_hours_start" => nil, "quiet_hours_end" => nil } end def quiet_now? hour = Time.current.hour if quiet_hours_start > quiet_hours_end hour >= quiet_hours_start || hour < quiet_hours_end else hour >= quiet_hours_start && hour < quiet_hours_end end end end ``` ## Anti-Patterns 1. **Using Active Record for non-persisted objects** — If there's no table, don't subclass `ApplicationRecord` 2. **Hand-rolling validations** — Don't write `raise "Name required" if name.blank?` when `validates :name, presence: true` exists 3. **Skipping `ActiveModel::Model`** — Don't manually implement `initialize(attrs={})` with hash iteration; `Model` does it 4. **Including everything** — Only include modules you use; `Model` is enough for most cases 5. **Forgetting `url:` in `form_with`** — Active Model objects don't auto-resolve routes 6. **Using `extend` where `include` is needed** — Callbacks use `extend`; everything else uses `include` 7. **Not wrapping multi-model saves in transactions** — Form objects that create multiple records need `ActiveRecord::Base.transaction` 8. **Reimplementing `assign_attributes`** — `ActiveModel::Model` already gives you attribute assignment from a hash via the initializer ## Reference For detailed patterns, edge cases, and advanced usage, see the `references/` directory: - `references/api-and-attributes.md` — Model vs API, typed attributes, naming, translation, conversion - `references/validations-and-callbacks.md` — All validators, custom validators, callbacks, error handling - `references/dirty-tracking.md` — Manual and automatic change tracking - `references/serialization.md` — serializable_hash, JSON serialization - `references/patterns.md` — Form objects, wizards, service objects, lint tests, edge cases