Name: draper
Owner: Turing School of Software & Design
Description: Decorators/View-Models for Rails Applications
Created: 2015-03-02 22:41:50.0
Updated: 2015-09-23 23:59:18.0
Pushed: 2015-03-12 09:44:53.0
Size: 1335
Language: Ruby
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Announcement: Draper is looking for a new maintainer. If you're interested, please join the conversation.
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.
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:
p/controllers/articles_controller.rb
show
rticle = Article.find(params[:id]).decorate
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.
Let's look at how you could convert an existing Rails helper to a decorator method. You have this existing helper:
p/helpers/articles_helper.rb
publication_status(article)
article.published?
"Published at #{article.published_at.strftime('%A, %B %e')}"
se
"Unpublished"
d
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 you'll have to 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:
@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.
Instead, you implement a decorator:
p/decorators/article_decorator.rb
s ArticleDecorator < Draper::Decorator
legate_all
f publication_status
if published?
"Published at #{published_at}"
else
"Unpublished"
end
d
f published_at
object.published_at.strftime("%A, %B %e")
d
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.
Decorators are the ideal place to:
name method that
combines first_name and last_name attributesurl field
into a hyperlinkAdd Draper to your Gemfile:
'draper', '~> 1.3'
And run bundle install within your app's directory.
If you're upgrading from a 0.x release, the major changes are outlined in the wiki.
Decorators inherit from Draper::Decorator, live in your app/decorators
directory, and are named for the model that they decorate:
p/decorators/article_decorator.rb
s ArticleDecorator < Draper::Decorator
.
When you have Draper installed and generate a controller…
s generate resource Article
…you'll get a decorator for free!
But if the Article model already exists, you can run…
s generate decorator Article
…to create the ArticleDecorator.
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:
s ArticleDecorator < Draper::Decorator
f emphatic
h.content_tag(:strong, "Awesome")
d
If writing h. frequently is getting you down, you can add…
ude Draper::LazyHelpers
…at the top of your decorator class - you'll mix in a bazillion methods and
never have to type h. again.
(Note: the capture method is only available through h or helpers)
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):
s ArticleDecorator < Draper::Decorator
f published_at
object.published_at.strftime("%A, %B %e")
d
Ok, so you've written a sweet decorator, now you're going to want to put it into
action! A simple option is to call the decorate method on your model:
icle = 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:
get = ProductDecorator.new(Widget.first)
, equivalently
get = ProductDecorator.decorate(Widget.first)
If you have a collection of objects, you can decorate them all in one fell swoop:
icles = ArticleDecorator.decorate_collection(Article.all)
If your collection is an ActiveRecord query, you can use this:
icles = Article.popular.decorate
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.
If you want to add methods to your decorated collection (for example, for
pagination), you can subclass Draper::CollectionDecorator:
p/decorators/articles_decorator.rb
s ArticlesDecorator < Draper::CollectionDecorator
f page_number
42
d
sewhere...
icles = ArticlesDecorator.new(Article.all)
, equivalently
icles = ArticlesDecorator.decorate(Article.all)
Draper decorates each item by calling the 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'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 object:
s PaginatingDecorator < Draper::CollectionDecorator
legate :current_page, :total_pages, :limit_value
The delegate method used here is the same as that added by Active Support,
except that the :to option is not required; it defaults to :object when
omitted.
will_paginate needs the following delegations:
gate :current_page, :per_page, :offset, :total_entries, :total_pages
You can automatically decorate associated models when the primary model is
decorated. Assuming an Article model has an associated Author object:
s ArticleDecorator < Draper::Decorator
corates_association :author
When ArticleDecorator decorates an Article, it will also use
AuthorDecorator to decorate the associated Author.
You can call decorates_finders in a decorator…
s ArticleDecorator < Draper::Decorator
corates_finders
…which allows you to then call all the normal ActiveRecord-style finders on
your ArticleDecorator and they'll return decorated objects:
icle = ArticleDecorator.find(params[:id])
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:
p/controllers/articles_controller.rb
s ArticlesController < ApplicationController
corates_assigned :article
f show
@article = Article.find(params[:id])
d
The decorates_assigned :article bit is roughly equivalent to
article
ecorated_article ||= @article.decorate
er_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.
Draper supports RSpec, MiniTest::Rails, and Test::Unit, and will add the appropriate tests when you generate a decorator.
Your specs are expected to live in spec/decorators. If you use a different
path, you need to tag them with type: :decorator.
In a controller spec, you might want to check whether your instance variables are being decorated properly. You can use the handy predicate matchers:
gns(:article).should be_decorated
, if you want to be more specific
gns(:article).should be_decorated_with ArticleDecorator
Note that model.decorate == model, so your existing specs shouldn't break when
you add the decoration.
In your Spork.prefork block of spec_helper.rb, add this:
ire 'draper/test/rspec_integration'
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:
er::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:
er::ViewContext.test_strategy :fast do
clude ApplicationHelper
If you are writing isolated tests for Draper methods that call route helper methods, you can stub them instead of needing to require Rails.
If you are using RSpec, minitest-rails, or the Test::Unit syntax of minitest,
you already have access to the Draper helpers in your tests since they
inherit from Draper::TestCase. If you are using minitest's spec syntax
without minitest-rails, you can explicitly include the Draper helpers:
ribe YourDecorator do
clude Draper::ViewHelpers
Then you can stub the specific route helper functions you need using your
preferred stubbing technique (this example uses RSpec's stub method):
ers.stub(users_path: '/users')
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:
p/decorators/application_decorator.rb
s ApplicationDecorator < Draper::Decorator
.
Then modify your decorators to inherit from that ApplicationDecorator instead
of directly from Draper::Decorator:
s ArticleDecorator < ApplicationDecorator
decorator 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
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:
s ArticleDecorator < Draper::Decorator
legate :title, :body
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:
s ArticleDecorator < Draper::Decorator
legate :title, :body
legate :name, :title, to: :author, prefix: true
From your view template, assuming @article is decorated, you could do any of
the following:
icle.title # Returns the article's `.title`
icle.body # Returns the article's `.body`
icle.author_name # Returns the article's `author.name`
icle.author_title # Returns the article's `author.title`
If you need to pass extra data to your decorators, you can use a context hash.
Methods that create decorators take it as an option, for example:
cle.first.decorate(context: {role: :admin})
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:
s ArticleDecorator < Draper::Decorator
corates_association :author, context: {foo: "bar"}
or, if you want to modify the parent's context, use a lambda that takes a hash and returns a new hash:
s ArticleDecorator < Draper::Decorator
corates_association :author,
context: ->(parent_context){ parent_context.merge(foo: "bar") }
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:
s ArticleDecorator < Draper::Decorator
corates_association :author, with: FancyPersonDecorator
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:
s ArticleDecorator < Draper::Decorator
corates_association :comments, scope: :recent
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.
If your model name can't be inferred from your decorator name in this way, you
need to use the decorates method:
s MySpecialArticleDecorator < Draper::Decorator
corates :article
This is only necessary when proxying class methods.
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 (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.