🧙 Magic Presenter

A bit of history: this gem was inspired by digging deeper into Draper with an eye on a refactoring.

Based on Magic Decorator, it implements a presenter logic.

Install the gem and add to the application's Gemfile by executing:

$ bundle add magic-presenter

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install magic-presenter

After all the gems are bundled run the installer in the project directory to generate the necessary files:

$ bin/rails generate magic:presenter:install

Magic::Presenter::Base is a basic presenter class to be inherited by any other presenter. It further inherits from SimpleDelegator.

class PersonPresenter < Magic::Presenter::Base
  def name = "#{first_name} #{last_name}"
end

class Person
  include ActiveModel::Model
  attr_accessor :first_name, :last_name
end

person = Person.new(first_name: 'John', last_name: 'Smith').decorate
person.name # => "John Smith"

This module includes Magic::Decoratable and allows a descendant to be decorated by presenters only. Presenter class is being inferred automatically. When no presenter is found,

• #decorate returns nil,
• #decorate! raises Magic::Lookup::Error,
• #decorated returns the original object.

A generator can be used to generate a presenter:

$ bin/rails generate presenter Person

See the help for more info:

$ bin/rails generate presenter --help

A presenter can use any helpers via #helpers (aliased as #h) both in class and instance methods:

class PersonPresenter < Magic::Presenter::Base
  def self.links
    [ h.link_to('All', model_class) ]
  end
  
  def link(...) 
    helpers.link_to(name, self, ...)
  end
end

A view context must be set to enable helpers. It’s done automagically wherever possible. However, one can set it explicitly anywhere:

Magic::Presenter.with view_context: ApplicationController.new.view_context do
  # put the code that uses helpers within presenters here
end

It’s based on Magic Decorator, so get familiar with that one as well.

Magic::Presentable is mixed into ActiveModel::API by default. It means that any model, be it ActiveRecord::Base, Mongoid::Document or whatever else, is magically presentable.

Presenters provide automatic class inference for any model based on its class name powered by Magic Lookup.

For example, MyNamespace::MyModel.new.decorate looks for MyNamespace::MyPresenter first. When missing, it further looks for decorators for its ancestor classes, up to ObjectPresenter.

• MyObject → MyObjectPresenter
• MyModel → MyPresenter
• MyRecord → MyPresenter

When in doubt, one can use Magic::Presenter.name_for:

Magic::Presenter.name_for Person # => "PersonPresenter"

This is done automatically in both test and production environments by Rails. All the application’s presenters and models are eagerly loaded before normal and reverse lookups by Magic Presenter as well. So, normally one shouldn’t worry about that.

That could be done in an initializer with a helper method provided:

Rails.application.config.to_prepare do
  Magic.eager_load :presenters, engine: MyLib::Engine
end

Missing class methods of a presenter are delegated to a matching model class if the latter can be inferred unambiguously. Magic::Lookup::Error is raised otherwise.

One can call helpers directly without explicit helper or h:

class PersonPresenter < Magic::Presenter::Base
  def self.links
    [ link_to('All', model_class) ]
  end

  def link(...) = link_to(name, self, ...)
end

View context is set automagically to enable helpers:

• in views,
• in controller actions,
• in mailer actions.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/Alexander-Senko/magic-presenter. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Magic Presenter project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.