rails-decorator-conventions

Rails Decorator Conventions

Conventions for Draper decorators in this project.

When to Use This Skill

Automatically activates when working on:

• app/decorators/**/*.rb

Use this skill when:

• Creating new decorators
• Adding display logic for model attributes
• Formatting values for views (currency, dates, status badges)
• Moving presentation logic out of views or helpers

Core Principles

1. Decorators = "how to display" - Presentation logic only. Models = "what is the state"
2. Inherit from Draper::Decorator - All decorators use Draper
3. Always use delegate_all - Forward all model methods transparently
4. Access view helpers via h. - Use h.link_to, h.number_to_currency, etc.
5. No business logic - Decorators never change state, only format it for display

Structure

# app/decorators/bond_decorator.rb
class BondDecorator < Draper::Decorator
  delegate_all

  # Currency formatting
  def formatted_amount
    h.number_to_currency(amount)
  end

  # Status badge with Bootstrap classes
  def status_badge
    h.content_tag(:span, status.titleize, class: "badge badge-#{status_color}")
  end

  # Date formatting
  def effective_date_display
    effective_date.strftime("%B %d, %Y")
  end

  # Conditional display
  def expiration_warning
    return unless expires_soon?

    h.content_tag(:span, "Expiring soon", class: "text-danger")
  end

  private

  def status_color
    case status
    when "approved" then "success"
    when "pending" then "warning"
    when "declined" then "danger"
    else "secondary"
    end
  end
end

Common Patterns

Currency Formatting

def formatted_premium
  h.number_to_currency(premium)
end

Status Badges

def status_badge
  h.content_tag(:span, status.titleize, class: "badge badge-#{status_css_class}")
end

Date Formatting

def created_display
  created_at.strftime("%B %d, %Y")
end

def updated_ago
  h.time_ago_in_words(updated_at) + " ago"
end

Conditional Display

def cancellation_notice
  return unless cancelled?

  h.content_tag(:div, "This bond has been cancelled", class: "alert alert-danger")
end

Usage in Controllers and Views

# Controller - single record
@bond = Bond.find(params[:id]).decorate

# Controller - collection
@bonds = Bond.where(status: "active").decorate

# View (Haml)
%h2= @bond.status_badge
%p= @bond.formatted_amount

# View (ERB)
<h2><%= @bond.status_badge %></h2>
<p><%= @bond.formatted_amount %></p>

Decorators vs Helpers vs Models

Logic	Where	Example
Domain/business	Model	bond.approved?, bond.cancel!
Model-specific display	Decorator	bond.decorate.formatted_amount
Generic view utility	Helper	yes_no(value), external_link(url)

Testing

Test decorators in spec/decorators/:

# spec/decorators/bond_decorator_spec.rb
RSpec.describe BondDecorator do
  let(:bond) { create(:bond, amount: 50000, status: "approved").decorate }

  describe "#formatted_amount" do
    it "formats as currency" do
      expect(bond.formatted_amount).to eq("$50,000.00")
    end
  end

  describe "#status_badge" do
    it "returns a success badge for approved bonds" do
      expect(bond.status_badge).to include("badge-success")
      expect(bond.status_badge).to include("Approved")
    end
  end
end

Quick Reference

Do	Don't
delegate_all	Cherry-pick delegations
h.number_to_currency(amount)	Format in view template
Presentation logic only	Business logic in decorator
Test in spec/decorators/	Skip decorator tests
Decorate in controller	Decorate in view

Common Mistakes

1. Business logic in decorators - Decorators format, they don't decide. State changes belong in models
2. Not using delegate_all - Always delegate so all model methods remain accessible
3. Forgetting h. prefix - View helpers must be accessed via h.
4. Decorating in views - Decorate in the controller, not in templates
5. Duplicating model logic - If the model has a method, call it; don't reimplement