Makeover
A decorator library for Rails applications, inspired by Draper, but with an emphasis on architectural simplicity. Makeover uses the given ActiveSupport and Ruby standard library objects that can help in building an object-presentation layer for your models.
Usage
After installing, run the following command to get things set up:
$ bin/rails makeover:install
This will mix in the Makeover::Presentable
module into your
ApplicationRecord
model code, enabling models to be presented by
calling model.present
. This module is also mixed into your
ApplicationController
, because the present
method can be called with
an optional first argument that dictates the model being presented. In
addition to mixing itself in (visibly) to your controller and model
layer, this generator also creates an ApplicationPresenter
and
CollectionPresenter
base class for presenting models and collections,
respectively. All makeover will be derived from one of these base
classes.
In your application code, presentation would look like the following:
class PostsController < ApplicationController
def index
@posts = present Post.search(params[:q])
end
def show
@post = Post.find(params[:id]).present
end
end
It is recommended to choose one syntax and make that standard across
your app, however both syntaxes are provided in case one or the other
works out better for you. Conventionally, presenter classes are found
by taking the model name and adding "Presenter" to the end, or in the
case of collections, pluralizing the model name and then suffixing with
"Presenter". You can customize this by passing the with:
option into
the #present
method:
@post.present with: SearchResultPresenter
You can also use this options hash to apply context into the presenter.
A call to #present
like this:
@post.present with: SearchResultPresenter, search: @search
Will result in the following instantiation:
SearchResultPresenter.new(@post, search: @search)
The Presenter Class
Makeover are subclasses of Makeover::Presenter
, which itself
subclasses (and implements Delegator. The Delegator API was designed
specifically for implementing decorator objects such as this, and it's
utilized here to delegate all method calls not implemented on the
presenter itself to its underlying model. In addition, the Presenter
class contains an instance of a Makeover::Helpers
object, which
mixes in ActionView::Helpers
as well as any modules you define in
Rails.application.config.makeover.helpers
.
This library is also capable of presenting entire collections of
objects. You can opt to present the collection object itself (like
in cases of pagination), or the objects within it. Collection makeover
derive from Makeover::CollectionPresenter
, and in your application
the base collection presenter is called CollectionPresenter
.
These types of objects can be generated using the --collection
flag on
the presenter generator (as described below), but they're also generated
automatically when you pass a plural name into the presenter generator.
Collection makeover are Enumerable objects, and when iterating
over their model
, all records inside the collection are decorated
prior to returning to the caller.
Generating Makeover
To generate a presenter, run the following command:
$ bin/rails generate presenter post
This will generate app/makeover/post_presenter.rb as a subclass fo
ApplicationPresenter
. It will also generate a test file in
test/makeover/post_presenter_test.rb or
spec/makeover/post_presenter_spec.rb.
A typical presenter might look like this:
class PostPresenter < ApplicationPresenter
def title
model.name.titleize
end
def cover_image
h.image_tag model.cover_image_url
end
end
You can also generate collection makeover using this generator. This can be done in one of two ways, either by passing a plural name into the generator:
$ bin/rails generate presenter posts
Or, by passing the --collection
option in the generator arguments:
$ bin/rails generate presenter query --collection
This will generate a presenter class that is subclassed from
CollectionPresenter
, rather than ApplicationPresenter
.
Configuring Makeover
To mix helper modules into your makeover, add the following to your config/application.rb:
config.makeover.helpers << Refile::AttachmentHelper # or whatever module you want
Installation
Add this line to your application's Gemfile:
gem 'makeover'
And then execute:
$ bundle
Or install it yourself as:
$ gem install makeover
Contributing
All contributions to this library must follow the Code of Conduct. Please follow the instructions laid out in the issue and pull request template for proper description formatting. We use GitHub Issues as a bug tracker, and only accept code contributions in the form of GitHub Pull Requests.
License
The gem is available as open source under the terms of the MIT License.