A simple decorator for Rails
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
gemfiles Preparing for 1.0.0.pre.1 release Jan 30, 2019
lib
spec
.editorconfig Initial commit Jan 29, 2019
.gitignore
.rspec
.rubocop.yml Initial commit Jan 29, 2019
.simplecov ci: use rubocop, simplecov and coverwalls Jan 29, 2019
.travis.yml ci: test with ruby2.6 Jan 29, 2019
Appraisals ci: install and configure appraisals Jan 29, 2019
CHANGELOG.md
CODE_OF_CONDUCT.md
Gemfile
Gemfile.lock Preparing for 1.0.0.pre.1 release Jan 30, 2019
LICENSE.txt
README.md Fix typos in README Feb 8, 2019
Rakefile
dekorator.gemspec docs: renaming from pantographe to komposable Feb 8, 2019

README.md

Dekorator

Build Status Gem Version Maintainability Coverage Status Inch CI Yardoc

Dekorator is an opinionated way of organizing model-view code in Ruby on Rails, based on decorators.

Not production ready yet

This gem has been created by Pantographe.

Compatibility

  • Ruby 2.3+
  • Rails 5.0+

Installation

Add this line to your application Gemfile:

gem "dekorator"

And then execute:

$ bundle

Getting started

Run the following command to set up your project:

$ rails generate dekorator:install

This command will create an ApplicationDecorator file.

Usage

Generate a new decorator with the decorator generator:

$ rails generate decorator user

This command will generate the following file:

class UserDecorator < ApplicationDecorator
  # include ActionView::Helpers::TextHelper
  #
  # decorates_association :posts
  #
  # def full_name
  #   [first_name, last_name].join(" ")
  # end
  #
  # def biography_summary
  #   truncate(biography, length: 170)
  # end
end

Associations

If you want to automatically decorate an association for a decorated object, you have to use #decorates_association as following:

class UserDecorator < ApplicationDecorator
  decorates_association :posts

  ...
end

class PostDecorator < ApplicationDecorator
  ...
end

In this example, UserDecorator#posts will be decorated.

decorated_user = decorator(User.first)
decorated_user # => UserDecorator
decorated_user.posts.first # => PostDecorator

Specify decorator

If you want to create a specific decorator or sub-decorator, you can simply specify the decorator class that should be used.

class AdminDecorator < ApplicationDecorator
end

decorated_user = decorator(User.first, with: AdminDecorator)
decorated_user # => AdminDecorator

You can also specify the decorator for associations:

class UserDecorator < ApplicationDecorator
  decorates_association :posts, ArticleDecorator

  ...
end

class ArticleDecorator < ApplicationDecorator
end

decorated_user = decorator(User.first)
decorated_user # => UserDecorator
decorated_user.posts.first # => ArticleDecorator

Compatibility

ActiveAdmin

This gem is compatible with activeadmin.

Simply use #decorate_with

# app/admin/post.rb
ActiveAdmin.register Post do
  decorate_with PostDecorator

  index do
    column :title
    column :image
    actions
  end
end

Devise

If you use the Devise gem you may have an issue if you decorate your User model.

You must define #devise_scope as following. Devise needs to manage with the User model (https://github.com/plataformatec/devise/blob/369ba267efaa10d01c8dba59b09c3b94dd9e5551/lib/devise/mapping.rb#L35).

class UserDecorator < ApplicationDecorator
  ...

  def devise_scope
    __getobj__
  end
end

Development

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. To release a new version, update the version number in version.rb, then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

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

License

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

Code of Conduct

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