README.md

Draper

Draper adds an object-oriented layer of presentation logic to your Rails application.

Without Draper, this functionality might have been tangled up in procedural helpers or adding bulk to your models. With Draper decorators, you can wrap your models with presentation-related logic to organise - and test - this layer of your app much more effectively.

Installation

Put this in your Gemfile :

git_source(:github){ |repo_name| "https://github.com/#{repo_name}.git" }

gem 'draper', github: 'jbox-web/draper', tag: '1.0.0'

then run bundle install.

Writing Decorators

Decorators inherit from Draper::Decorator, live in your app/decorators directory, and are named for the model that they decorate:

# app/decorators/article_decorator.rb
class ArticleDecorator < Draper::Decorator
# ...
end

Accessing Helpers

Normal Rails helpers are still useful for lots of tasks. Both Rails' provided helpers and those defined in your app can be accessed within a decorator via the h method:

class ArticleDecorator < Draper::Decorator
  def emphatic
    h.content_tag(:strong, "Awesome")
  end
end

Accessing the model

When writing decorator methods you'll usually need to access the wrapped model. While you may choose to use delegation (covered below) for convenience, you can always use the object (or its alias model):

class ArticleDecorator < Draper::Decorator
  def published_at
    object.published_at.strftime("%A, %B %e")
  end
end

Decorating Associated Objects

You can automatically decorate associated models when the primary model is decorated. Assuming an Article model has an associated Author object:

class ArticleDecorator < Draper::Decorator
  decorates_association :author
end

When ArticleDecorator decorates an Article, it will also use AuthorDecorator to decorate the associated Author.

Delegating Methods

When your decorator calls delegate_all, any method called on the decorator not defined in the decorator itself will be delegated to the decorated object. This includes calling super from within the decorator. A call to super from within the decorator will first try to call the method on the parent decorator class. If the method does not exist on the parent decorator class, it will then try to call the method on the decorated object. This is a very permissive interface.

If you want to strictly control which methods are called within views, you can choose to only delegate certain methods from the decorator to the source model:

class ArticleDecorator < Draper::Decorator
  delegate :title, :body
end

We omit the :to argument here as it defaults to the object being decorated. You could choose to delegate methods to other places like this:

class ArticleDecorator < Draper::Decorator
  delegate :title, :body
  delegate :name, :title, to: :author, prefix: true
end

From your view template, assuming @article is decorated, you could do any of the following:

@article.title # Returns the article's `.title`
@article.body  # Returns the article's `.body`
@article.author_name  # Returns the article's `author.name`
@article.author_title # Returns the article's `author.title`