Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 2539f8b30d

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 Gemfile
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 basic_decorator.gemspec
README.md

BasicDecorator

Build Status Generated documentation on Rubydoc.info

Decoration in Ruby should be easy. With BasicDecorator, it is.

BasicDecorator was spawned by my Gist in response to this post on the thoughtbot blog.

Installation

Make sure you're running Ruby 1.9 (BasicDecorator::Decorator, the meat and potatoes of the gem, inherits from Ruby's BasicObject, which is 1.9+).

Add this line to your application's Gemfile:

gem 'basic_decorator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install basic_decorator

Usage

Decorators are a wonderful design pattern allowing a developer to modify, extend, or otherwise change the behavior of an object while maintaining its interface. Remember ActiveSupport's alias_method_chain? That was essentially an inline (bastardized) decoration that mutated the object. If you want to read about the Decorator pattern, I suggest you check out:

Knowing about decorators, where does BasicDecorator fall? How do you use it?

Your decorators inherit from BasicDecorator::Decorator and you'll have access to the instance variable @component, the object passed in to the decorator's constructor.

Let's start off with the common 'Coffee', 'Cream', and 'Sugar' example. Here's our first object, Coffee.

class Coffee
  def cost
    Money.new(250, 'USD')
  end

  def origin
    'Columbia'
  end

  def additional_ingredients
    []
  end
end

Fairly straightforward. Let's write up decorators for Cream and Sugar.

class Cream < BasicDecorator::Decorator
  def cost
    @component.cost + ::Money.new(75, 'USD')
  end

  def additional_ingredients
    @component.additional_ingredients + ['Cream']
  end
end

class Sugar < BasicDecorator::Decorator
  def cost
    @component.cost + ::Money.new(25, 'USD')
  end

  def additional_ingredients
    @component.additional_ingredients + ['Sugar']
  end
end

If a method isn't defined on the decorator, it gets delegated to the @component (via method_missing), meaning it'll keep your decorators nice and thin; only define the methods of whom you want to change the behavior.

Sugar and Cream may decorate Coffee any number of times.

coffee = Coffee.new
# #<Coffee:0x007fb78a8c5ae8>
tasty_coffee = Sugar.new(Cream.new(coffee))
# #<Coffee:0x007fb78a8c5ae8>

coffee.cost
# #<Money cents:250 currency:USD>
tasty_coffee.cost
# #<Money cents:350 currency:USD>

coffee.additional_ingredients
# []
tasty_coffee.additional_ingredients
# ["Cream", "Sugar"]

tasty_coffee.is_a? Coffee
# true

You may want to be careful of decorating objects like arrays. Decoration typically won't mutate the component you're decorating; again, just something to be aware of.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Author

Written 2012 by Josh Clayton

License

Check the LICENSE

Something went wrong with that request. Please try again.