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.
Imagine your application has an `Article` model. With Draper, you'd create a corresponding `ArticleDecorator`. The decorator wraps the model, and deals *only* with presentational concerns. In the controller, you decorate the article before handing it off to the view:
In the view, you can use the decorator in exactly the same way as you would have used the model. But whenever you start needing logic in the view or start thinking about a helper method, you can implement a method on the decorator instead.
But it makes you a little uncomfortable. `publication_status` lives in a nebulous namespace spread across all controllers and view. Down the road, you might want to display the publication status of a `Book`. And, of course, your design calls for a slighly different formatting to the date for a `Book`.
Now your helper method can either switch based on the input class type (poor Ruby style), or you break it out into two methods, `book_publication_status` and `article_publication_status`. And keep adding methods for each publication type...to the global helper namespace. And remember all the names. Ick.
Ruby thrives when we use Object-Oriented style. If you didn't know Rails' helpers existed, you'd probably imagine that your view template could feature something like this:
```erb
<%= @article.publication_status %>
```
Without a decorator, you'd have to implement the `publication_status` method in the `Article` model. That method is presentation-centric, and thus does not belong in a model.
Within the `publication_status` method we use the `published?` method. Where does that come from? It's a method of the source `Article`, whose methods have been made available on the decorator by the `delegate_all` call above.
You might have heard this sort of decorator called a "presenter", an "exhibit", a "view model", or even just a "view" (in that nomenclature, what Rails calls "views" are actually "templates"). Whatever you call it, it's a great way to replace procedural helpers like the one above with "real" object-oriented programming.
When writing decorator methods you'll usually need to access the wrapped model. While you may choose to use delegation ([covered below](#delegating-methods)) for convenience, you can always use the `source` (or its alias `model`):
Ok, so you've written a sweet decorator, now you're going to want to put it in action! A simple option is to call the `decorate` method on your model:
```ruby
@article = Article.first.decorate
```
This infers the decorator from the object being decorated. If you want more control - say you want to decorate a `Widget` with a more general `ProductDecorator` - then you can instantiate a decorator directly:
*Note:* In Rails 3, the `.all` method returns an array and not a query. Thus you _cannot_ use the technique of `Article.all.decorate` in Rails 3. In Rails 4, `.all` returns a query so this techique would work fine.
Draper decorates each item using its `decorate` method. Alternatively, you can specify a decorator by overriding the collection decorator's `decorator_class` method, or by passing the `:with` option to the constructor.
Some pagination gems add methods to `ActiveRecord::Relation`. For example, [Kaminari](https://github.com/amatsuda/kaminari)'s `paginate` helper method requires the collection to implement `current_page`, `total_pages`, and `limit_value`. To expose these on a collection decorator, you can delegate to the `source`:
The `delegate` method used here is the same as that added by [Active Support](http://api.rubyonrails.org/classes/Module.html#method-i-delegate), except that the `:to` option is not required; it defaults to `:source` when omitted.
Decorators are supposed to behave very much like the models they decorate, and for that reason it is very tempting to just decorate your objects at the start of your controller action and then use the decorators throughout. *Don't*.
Because decorators are designed to be consumed by the view, you should only be accessing them there. Manipulate your models to get things ready, then decorate at the last minute, right before you render the view. This avoids many of the common pitfalls that arise from attempting to modify decorators (in particular, collection decorators) after creating them.
To help you make your decorators read-only, we have the `decorates_assigned` method in your controller. It adds a helper method that returns the decorated version of an instance variable:
```ruby
# app/controllers/articles_controller.rb
class ArticlesController <ApplicationController
decorates_assigned :article
def show
@article = Article.find(params[:id])
end
end
```
The `decorates_assigned :article` bit is roughly equivalent to
```ruby
def article
@decorated_article ||= @article.decorate
end
helper_method :article
```
This means that you can just replace `@article` with `article` in your views and you'll have access to an ArticleDecorator object instead. In your controller you can continue to use the `@article` instance variable to manipulate the model - for example, `@article.comments.build` to add a new blank comment for a form.
In tests, Draper needs to build a view context to access helper methods. By default, it will create an `ApplicationController` and then use its view context. If you are speeding up your test suite by testing each component in isolation, you can eliminate this dependency by putting the following in your `spec_helper` or similar:
```ruby
Draper::ViewContext.test_strategy :fast
```
In doing so, your decorators will no longer have access to your application's helpers. If you need to selectively include such helpers, you can pass a block:
You might have several decorators that share similar needs. Since decorators are just Ruby objects, you can use any normal Ruby technique for sharing functionality.
In Rails controllers, common functionality is organized by having all controllers inherit from `ApplicationController`. You can apply this same pattern to your decorators:
When your decorator calls `delegate_all`, any method called on the decorator not defined in the decorator itself will be delegated to the decorated source. 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:
The value passed to the `:context` option is then available in the decorator through the `context` method.
If you use `decorates_association`, the context of the parent decorator is passed to the associated decorators. You can override this with the `:context` option:
When you're using `decorates_association`, Draper uses the `decorate` method on the associated record(s) to perform the decoration. If you want use a specific decorator, you can use the `:with` option:
For a collection association, you can specify a `CollectionDecorator` subclass, which is applied to the whole collection, or a singular `Decorator` subclass, which is applied to each item individually.
If you want your decorated association to be ordered, limited, or otherwise scoped, you can pass a `:scope` option to `decorates_association`, which will be applied to the collection *before* decoration:
If you want to proxy class methods to the wrapped model class, including when using `decorates_finders`, Draper needs to know the model class. By default, it assumes that your decorators are named `SomeModelDecorator`, and then attempts to proxy unknown class methods to `SomeModel`.
Models get their `decorate` method from the `Draper::Decoratable` module, which is included in `ActiveRecord::Base` and `Mongoid::Document` by default. If you're [using another ORM](https://github.com/drapergem/draper/wiki/Using-other-ORMs) (including versions of Mongoid prior to 3.0), or want to decorate plain old Ruby objects, you can include this module manually.
Draper was conceived by Jeff Casimir and heavily refined by Steve Klabnik and a great community of open source [contributors](https://github.com/drapergem/draper/contributors).
