drape 1.0.0.beta1

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+
+services:
+  - mongodb
+
+rvm:
+  - 2.3.1
+
+env:
+  - "RAILS_VERSION=5.0"
+
+addons:
+  code_climate:
+    repo_token: 85e7394726a531f2ae6520456b1f44488c4c22fc656cda26b843eb2eb4b58612

data/.yardopts

@@ -0,0 +1 @@
+yardoc 'lib/drape/**/*.rb' -m markdown --no-private

data/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Drape Changelog
+
+## 2.1.0 - 2015-03-26
+
+* Cleared most issues and merged a few PRs
+* Improved behavior when decorating structs
+* Improved how equality is handled
+* Minor improvements to the README
+
+## 2.0.0 - 2015-03-26
+
+Working to breathe new life into the project by shedding baggage.
+
+* Rails 3.2 support dropped
+* Ruby 1.9.3 and 2.0 support dropped
+* Add support for Rails 4.2 and Ruby 2.2
+* Rewrite tests to get over RSpec deprecations
+* Get RSpec up to 3.2
+* Try to un-screw the challenges of ActiveModelSerializers
+
+Due to the breakages of dropping legacy support, we've bumped the major version. From here,
+development effort will likely focus on a version 3.0 that removes features and simplifies
+usage of the library.
+
+## 1.3.0 - 2013-10-26
+
+[30 commits by 11 authors](https://github.com/drapegem/drape/compare/v1.2.1...v1.3.0)
+
+* [Add `decorator_class?` method](https://github.com/drapegem/drape/commit/53e1df5c3ee169144a2778c6d2ee13cc6af99429)
+
+* [Clear ViewContext before specs instead of after](https://github.com/drapegem/drape/pull/547)
+
+* [Add alias method `#{model_name}` to the decorated object ](https://github.com/drapegem/drape/commit/f5f27243c3f0c37bff4872e1e78521e570ff1e4f)
+
+* [Hook into `controller_generator` and `scaffold_controller_generator` instead of resource generator](https://github.com/drapegem/drape/commit/cd4f298987c3b4ad8046563ad4a087055fc7efe2)
+
+* [Delegate `to_s` method to the object](https://github.com/drapegem/drape/commit/58b8181050c2a9a86f54660e7bb6bfefa5fd0b64)
+
+## 1.2.1 - 2013-05-05
+
+[28 commits by 4 authors](https://github.com/drapegem/drape/compare/v1.2.0...v1.2.1)
+
+* [Document stubbing route helpers](https://github.com/drapegem/drape/commit/dbe8a81ca7d4d9ae87b4b62926a0ba6379397fbc)
+
+* [Rename `source` to `object`. `source` still works, but will be deprecated in a future release.](https://github.com/drapegem/drape/commit/4b933ef39d252ecfe93c573a072633be545c49fb)
+
+Various bugfixes, as always.
+
+## 1.2.0 - 2013-04-01
+
+[78 commits by 14 authors](https://github.com/drapegem/drape/compare/v1.1.0...v1.2.0)
+
+* [Added license to the gemspec](https://github.com/drapegem/drape/commit/731fa85f7744a12da1364a3aa94cdf6994efa9e2)
+
+* [Improvements in serialization](https://github.com/drapegem/drape/pull/448)
+
+* [Fix support for Guard in development](https://github.com/drapegem/drape/commit/93c95200277fd3922e30e74c7a7e05563747e896)
+
+* [Improved support for #capture](https://github.com/drapegem/drape/commit/efb934a6f59b9d8afe4a7fe29e9a94aae983b05c)
+
+* [CollectionDecorator now has #decorated?](https://github.com/drapegem/drape/commit/65e3c4e4573173b510440b7e80f95a87109a1d15)
+
+* [Added #respond_to_missing?](https://github.com/drapegem/drape/commit/11bb59bcf89f8e0be4ba2851eb78634caf783ecd)
+
+* [Add proper STI support](https://github.com/drapegem/drape/commit/7802d97446cf6ea130a66c2781f5a7a087d28c0a)
+
+* [Added before_remove_const callback for ActiveSupport](https://github.com/drapegem/drape/commit/9efda27c6a4f8680df4fad8f67ecb58e3f91703f)
+
+* [Accept a lambda for context](https://github.com/drapegem/drape/commit/3ab3b35e875b8b2bd99a57e4add388313e765230)
+
+* [Start testing against Ruby 2.0.0](https://github.com/drapegem/drape/commit/dbd1cbceedb0ddb3f060196cd31eb967db8a370b)
+
+* [Fix our use of #scoped per Rails 4 deprecation](https://github.com/haines/drape/commit/47ee29c3b739eee3fc28a561432ad2363c14813c)
+
+* [Properly swallow NameErrors](https://github.com/haines/drape/commit/09ad84fb712a30dd4302b9daa03d11281ac7d169)
+
+* [Delegate CollectionDecorator#kind_of? to the underlying collection](https://github.com/drapegem/drape/commit/d5975f2c5b810306a96d9485fd39d550896dc2a1)
+
+* [Make CollectionDecorators respond to #decorated_with?](https://github.com/drapegem/drape/commit/dc430b3e82de0d9cae86f7297f816e5b69d9ca58)
+
+* [Avoid using #extend in Decorator#== for performance reasons](https://github.com/drapegem/drape/commit/205a0d43b4141f7b1756fe2b44b877545eb37517)
+
+## 1.1.0 - 2013-01-28
+
+[44 commits by 6 authors](https://github.com/drapegem/drape/compare/v1.0.0...v1.1.0)
+
+* README improvements.
+* Rails 4 compatibility.
+  [b2401c7](https://github.com/drapegem/drape/commit/b2401c71e092470e3b912b5da475115c22b55734)
+* Added support for testing decorators without loading `ApplicationController`.
+  See the [README](https://github.com/drapegem/drape/blob/v1.1.0/README.md#isolated-tests) for details.
+  [4d0181f](https://github.com/drapegem/drape/commit/4d0181fb9c65dc769b05ed19bfcec2119d6e88f7)
+* Improved the `==` method to check for `decorated?` before attempting to
+  compare with `source`.
+  [6c31617](https://github.com/drapegem/drape/commit/6c316176f5039a5861491fbcaa81f64ac4b36768)
+* Changed the way helpers are accessed, so that helper methods may be stubbed
+  in tests.
+  [7a04619](https://github.com/drapegem/drape/commit/7a04619a06f832801bd4aedaaf5985d6e3e5e1af)
+* Made the Devise test helper `sign_in` method independent of mocking
+  framework.
+  [b0902ab](https://github.com/drapegem/drape/commit/b0902ab0fe01916b7fddb0a3d97aa0c7cca09482)
+* Stopped attempting to call `to_a` on decorated objects (a now-redundant lazy
+  query workaround).
+  [34c6390](https://github.com/drapegem/drape/commit/34c6390583f7fc7704d04e38bc974b65fc92517c)
+* Fixed a minor bug where view contexts could be accidentally shared between
+  tests.
+  [3d07cb3](https://github.com/drapegem/drape/commit/3d07cb387b1cae6f97897dfb85512e30f5e888e9)
+* Improved helper method performance.
+  [e6f88a5](https://github.com/drapegem/drape/commit/e6f88a5e7dada3f9db480e13e16d1acc964ba098)
+* Our specs now use the new RSpec `expect( ).to` syntax.
+  [9a3b319](https://github.com/drapegem/drape/commit/9a3b319d6d54cd78fb2654a94bbe893e36359754)
+
+## 1.0.0 - 2013-01-14
+
+[249 commits by 19 authors](https://github.com/drapegem/drape/compare/v0.18.0...v1.0.0)
+
+Major changes are described [in the upgrade guide](https://github.com/drapegem/drape/wiki/Upgrading-to-1.0).
+
+* Infer collection decorators.
+  [e8253df](https://github.com/drapegem/drape/commit/e8253df7dc6c90a542444c0f4ef289909fce4f90)
+* Prevent calls to `scoped` on decorated associations.
+  [5dcc6c3](https://github.com/drapegem/drape/commit/5dcc6c31ecf408753158d15fed9fb23fbfdc3734)
+* Add `helper` method to tests.
+  [551961e](https://github.com/drapegem/drape/commit/551961e72ee92355bc9c848bedfcc573856d12b0)
+* Inherit method security.
+  [1865ed3](https://github.com/drapegem/drape/commit/1865ed3e3b2b34853689a60b59b8ce9145674d1d)
+* Test against all versions of Rails 3.
+  [1865ed3](https://github.com/drapegem/drape/commit/1865ed3e3b2b34853689a60b59b8ce9145674d1d)
+* Pretend to be `instance_of?(source.class)`.
+  [30d209f](https://github.com/drapegem/drape/commit/30d209f990847e84b221ac798e84b976f5775cc0)
+* Remove security from `Decorator`. Do manual delegation with `:delegate`.
+  [c6f8aaa](https://github.com/drapegem/drape/commit/c6f8aaa2b2bd4679738050aede2503aa8e9db130)
+* Add generators for MiniTest.
+  [1fac02b](https://github.com/drapegem/drape/commit/1fac02b65b15e32f06e8292cb858c97cb1c1da2c)
+* Test against edge rails.
+  [e9b71e3](https://github.com/drapegem/drape/commit/e9b71e3cf55a800b48c083ff257a7c1cbe1b601b)
+
+### 1.0.0.beta6 - 2012-12-31
+
+* Fix up README to include changes made.
+  [5e6e4d1](https://github.com/drapegem/drape/commit/5e6e4d11b1e0c07c12b6b1e87053bc3f50ef2ab6)
+* `CollectionDecorator` no longer freezes its collection: direct access is
+  discouraged by making access private.
+  [c6d60e6](https://github.com/drapegem/drape/commit/c6d60e6577ed396385f3f1151c3f188fe47e9a57)
+* A fix for `Decoratable#==`.
+  [e4fa239](https://github.com/drapegem/drape/commit/e4fa239d84e8e9d6a490d785abb3953acc28fa65)
+* Ensure we coerce to an array in the right place.
+  [9eb9fc9](https://github.com/drapegem/drape/commit/9eb9fc909c372ea1c2392d05594fa75a5c08b095)
+
+### 1.0.0.beta5 - 2012-12-27
+
+* Change CollectionDecorator to freeze its collection.
+  [04d7796](https://github.com/drapegem/drape/commit/04d779615c43580409083a71661489e1bbf91ad4)
+* Bugfix on `CollectionDecorator#to_s`.
+  [eefd7d0](https://github.com/drapegem/drape/commit/eefd7d09cac97d531b9235246378c3746d153f08)
+* Upgrade `request_store` dependency to take advantage of a bugfix.
+  [9f17212](https://github.com/drapegem/drape/commit/9f17212fd1fb656ef1314327d60fe45e0acf60a2)
+
+### 1.0.0.beta4 - 2012-12-18
+
+* Fixed a race condition with capybara integration.
+  [e794649](https://github.com/drapegem/drape/commit/e79464931e7b98c85ed5d78ed9ca38d51f43006e)
+* `[]` can be decorated again.
+  [597fbdf](https://github.com/drapegem/drape/commit/597fbdf0c80583f5ea6df9f7350fefeaa0cca989)
+* `model == decorator` as well as `decorator == model`.
+  [46f8a68](https://github.com/drapegem/drape/commit/46f8a6823c50c13e5c9ab3c07723f335c4e291bc)
+* Preliminary Mongoid integration.
+  [892d195](https://github.com/drapegem/drape/commit/892d1954202c61fd082a07213c8d4a23560687bc)
+* Add a helper method `sign_in` for devise in decorator specs.
+  [66a3009](https://github.com/drapegem/drape/commit/66a30093ed4207d02d8fa60bda4df2da091d85a3)
+* Brought back `context`.
+  [9609156](https://github.com/drapegem/drape/commit/9609156b997b3a469386eef3a5f043b24d8a2fba)
+* Fixed issue where classes were incorrectly being looked up.
+  [ee2a015](https://github.com/drapegem/drape/commit/ee2a015514ff87dfd2158926457e988c2fc3fd79)
+* Integrate RequestStore for per-request storage.
+  [fde1cde](https://github.com/drapegem/drape/commit/fde1cde9adfb856750c1f616d8b62d221ef97fc6)
+
+### 1.0.0.beta3 - 2012-12-03
+
+* Relaxed Rails version requirement to 3.0. Support for < 3.2 should be
+  considered experimental. Please file bug reports.
+
+### 1.0.0.beta2 - 2012-12-03
+
+* `has_finders` is now `decorates_finders`.
+  [33f18aa](https://github.com/drapegem/drape/commit/33f18aa062e0d3848443dbd81047f20d5665579f)
+* If a finder method is used, and the source class is not set and cannot be
+  inferred, an `UninferrableSourceError` is raised.
+  [8ef5bf2](https://github.com/drapegem/drape/commit/8ef5bf2f02f7033e3cd4f1f5de7397b02c984fe3)
+* Class methods are now properly delegated again.
+  [731995a](https://github.com/drapegem/drape/commit/731995a5feac4cd06cf9328d2892c0eca9992db6)
+* We no longer `respond_to?` private methods on the source.
+  [18ebac8](https://github.com/drapegem/drape/commit/18ebac81533a6413aa20a3c26f23e91d0b12b031)
+* Rails versioning relaxed to support Rails 4.
+  [8bfd393](https://github.com/drapegem/drape/commit/8bfd393b5baa7aa1488076a5e2cb88648efaa815)
+
+### 1.0.0.beta1 - 2012-11-30
+
+* Renaming `Drape::Base` to `Drape::Decorator`. This is the most significant
+  change you'll need to upgrade your application.
+  [025742c](https://github.com/drapegem/drape/commit/025742cb3b295d259cf0ecf3669c24817d6f2df1)
+* Added an internal Rails application for integration tests. This won't affect
+  your application, but we're now running a set of Cucumber tests inside of a
+  Rails app in both development and production mode to help ensure that we
+  don't make changes that break Drape.
+  [90a4859](https://github.com/drapegem/drape/commit/90a4859085cab158658d23d77cd3108b6037e36f)
+* Add `#decorated?` method. This gives us a free RSpec matcher,
+  `be_decorated`.
+  [834a6fd](https://github.com/drapegem/drape/commit/834a6fd1f24b5646c333a04a99fe9846a58965d6)
+* `#decorates` is no longer needed inside your models, and should be removed.
+  Decorators automatically infer the class they decorate.
+  [e1214d9](https://github.com/drapegem/drape/commit/e1214d97b62f2cab45227cc650029734160dcdfe)
+* Decorators do not automatically come with 'finders' by default. If you'd like
+  to use `SomeDecorator.find(1)`, for example, simply add `#has_finders` to
+  the decorator to include them.
+  [42b6f78](https://github.com/drapegem/drape/commit/42b6f78fda4f51845dab4d35da68880f1989d178)
+* To refer to the object being decorated, `#source` is now the preferred
+  method.
+  [1e84fcb](https://github.com/drapegem/drape/commit/1e84fcb4a0eab0d12f5feda6886ce1caa239cb16)
+* `ActiveModel::Serialization` is included in Decorators if you've requred
+  `ActiveModel::Serializers`, so that decorators can be serialized.
+  [c4b3527](https://github.com/drapegem/drape/commit/c4b352799067506849abcbf14963ea36abda301c)
+* Properly support Test::Unit.
+  [087e134](https://github.com/drapegem/drape/commit/087e134ed0885ec11325ffabe8ab2bebef77a33a)
+
+And many small bug fixes and refactorings.
+
+## 0.x
+
+See changes prior to version 1.0 [here](https://github.com/drapegem/drape/blob/16140fed55f57d18f8b10a0789dd1fa5b3115a8d/CHANGELOG.markdown).

data/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+Contributing to Drape
+===================
+
+First of all, **thank you** for wanting to help and reading this!
+
+If you have found a problem with Drape, please [check to see](https://github.com/drapegem/drape/issues) if there's already an issue and if there's not, [create a new report](https://github.com/drapegem/drape/issues/new). Please include your versions of Drape and Rails (and any other gems that are relevant to your issue, e.g. RSpec if you're having trouble in your tests).
+
+## Sending a pull request
+
+Thanks again! Here's a quick how-to:
+
+1. [Fork the project](https://help.github.com/articles/fork-a-repo).
+2. Create a branch - `git checkout -b adding_magic`
+3. Make your changes, and add some tests!
+4. Check that the tests pass - `bundle exec rake`
+5. Commit your changes - `git commit -am "Added some magic"`
+6. Push the branch to Github - `git push origin adding_magic`
+7. Send us a [pull request](https://help.github.com/articles/using-pull-requests)!
+
+:heart: :sparkling_heart: :heart:

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gemspec
+
+platforms :ruby do
+  gem 'sqlite3'
+end
+
+platforms :jruby do
+  gem 'minitest', '>= 3.0'
+  gem 'activerecord-jdbcsqlite3-adapter', '>= 1.3.0.beta2'
+end
+
+version = ENV['RAILS_VERSION'] || '5.0'
+
+eval_gemfile File.expand_path("../gemfiles/#{version}.gemfile", __FILE__)

data/Guardfile

@@ -0,0 +1,26 @@
+def rspec_guard(options = {}, &block)
+  options = {
+    version: 2,
+    notification: false
+  }.merge(options)
+
+  guard 'rspec', options, &block
+end
+
+rspec_guard spec_paths: %w(spec/drape spec/generators) do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+end
+
+rspec_guard spec_paths: 'spec/integration', env: { 'RAILS_ENV' => 'development' } do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+end
+
+rspec_guard spec_paths: 'spec/integration', env: { 'RAILS_ENV' => 'production' } do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+end

data/LICENSE

@@ -0,0 +1,7 @@
+(The MIT License)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,592 @@
+# Drape: View Models for Rails
+
+[![TravisCI Build Status](https://travis-ci.org/MrEmelianenko/drape.svg?branch=master)](http://travis-ci.org/MrEmelianenko/drape)
+[![Code Climate](https://codeclimate.com/github/MrEmelianenko/drape/badges/gpa.svg)](https://codeclimate.com/github/MrEmelianenko/drape)
+[![Inline docs](http://inch-ci.org/github/MrEmelianenko/drape.svg?branch=master)](http://inch-ci.org/github/MrEmelianenko/drape)
+
+Drape adds an object-oriented layer of presentation logic to your Rails
+application.
+
+Without Drape, this functionality might have been tangled up in procedural
+helpers or adding bulk to your models. With Drape decorators, you can wrap your
+models with presentation-related logic to organise - and test - this layer of
+your app much more effectively.
+
+## Drape this is Draper?
+
+Yes, but Drape adapted for Ruby on Rails 5.
+
+## Why Use a Decorator?
+
+Imagine your application has an `Article` model. With Drape, 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:
+
+```ruby
+# app/controllers/articles_controller.rb
+def show
+  @article = Article.find(params[:id]).decorate
+end
+```
+
+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:
+
+```ruby
+# app/helpers/articles_helper.rb
+def publication_status(article)
+  if article.published?
+    "Published at #{article.published_at.strftime('%A, %B %e')}"
+  else
+    "Unpublished"
+  end
+end
+```
+
+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:
+
+```erb
+<%= @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:
+
+```ruby
+# app/decorators/article_decorator.rb
+class ArticleDecorator < Drape::Decorator
+  delegate_all
+
+  def publication_status
+    if published?
+      "Published at #{published_at}"
+    else
+      "Unpublished"
+    end
+  end
+
+  def published_at
+    object.published_at.strftime("%A, %B %e")
+  end
+end
+```
+
+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:
+* format complex data for user display
+* define commonly-used representations of an object, like a `name` method that
+  combines `first_name` and `last_name` attributes
+* mark up attributes with a little semantic HTML, like turning a `url` field
+  into a hyperlink
+
+## Installation
+
+Add Drape to your Gemfile:
+
+```ruby
+gem 'drape', '~> 1.0.0.beta1'
+```
+
+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](https://github.com/drapegem/drape/wiki/Upgrading-to-1.0).
+
+## Writing Decorators
+
+Decorators inherit from `Drape::Decorator`, live in your `app/decorators`
+directory, and are named for the model that they decorate:
+
+```ruby
+# app/decorators/article_decorator.rb
+class ArticleDecorator < Drape::Decorator
+# ...
+end
+```
+
+### Generators
+
+When you have Drape installed and generate a controller...
+
+```
+rails generate resource Article
+```
+
+...you'll get a decorator for free!
+
+But if the `Article` model already exists, you can run...
+
+```
+rails generate decorator Article
+```
+
+...to create the `ArticleDecorator`.
+
+### Accessing Helpers
+
+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:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  def emphatic
+    h.content_tag(:strong, "Awesome")
+  end
+end
+```
+
+If writing `h.` frequently is getting you down, you can add...
+
+```
+include Drape::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`)
+
+### Accessing the model
+
+When writing decorator methods you'll usually need to access the wrapped model.
+While you may choose to use delegation ([covered below](#delegating-methods))
+for convenience, you can always use the `object` (or its alias `model`):
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  def published_at
+    object.published_at.strftime("%A, %B %e")
+  end
+end
+```
+
+## Decorating Objects
+
+### Single Objects
+
+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:
+
+```ruby
+@article = 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:
+
+```ruby
+@widget = ProductDecorator.new(Widget.first)
+# or, equivalently
+@widget = ProductDecorator.decorate(Widget.first)
+```
+
+### Collections
+
+#### Decorating Individual Elements
+
+If you have a collection of objects, you can decorate them all in one fell
+swoop:
+
+```ruby
+@articles = ArticleDecorator.decorate_collection(Article.all)
+```
+
+If your collection is an ActiveRecord query, you can use this:
+
+```ruby
+@articles = 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.
+
+#### Decorating the Collection Itself
+
+If you want to add methods to your decorated collection (for example, for
+pagination), you can subclass `Drape::CollectionDecorator`:
+
+```ruby
+# app/decorators/articles_decorator.rb
+class ArticlesDecorator < Drape::CollectionDecorator
+  def page_number
+    42
+  end
+end
+
+# elsewhere...
+@articles = ArticlesDecorator.new(Article.all)
+# or, equivalently
+@articles = ArticlesDecorator.decorate(Article.all)
+```
+
+Drape 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.
+
+#### Using pagination
+
+Some pagination gems add methods to `ActiveRecord::Relation`. For example,
+[Kaminari](https://github.com/amatsuda/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`:
+
+```ruby
+class PaginatingDecorator < Drape::CollectionDecorator
+  delegate :current_page, :total_pages, :limit_value, :entry_name, :total_count, :offset_value, :last_page?
+end
+```
+
+The `delegate` method used here is the same as that added by [Active
+Support](http://api.rubyonrails.org/classes/Module.html#method-i-delegate),
+except that the `:to` option is not required; it defaults to `:object` when
+omitted.
+
+[will_paginate](https://github.com/mislav/will_paginate) needs the following delegations:
+
+```ruby
+delegate :current_page, :per_page, :offset, :total_entries, :total_pages
+```
+
+### Decorating Associated Objects
+
+You can automatically decorate associated models when the primary model is
+decorated. Assuming an `Article` model has an associated `Author` object:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  decorates_association :author
+end
+```
+
+When `ArticleDecorator` decorates an `Article`, it will also use
+`AuthorDecorator` to decorate the associated `Author`.
+
+### Decorated Finders
+
+You can call `decorates_finders` in a decorator...
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  decorates_finders
+end
+```
+
+...which allows you to then call all the normal ActiveRecord-style finders on
+your `ArticleDecorator` and they'll return decorated objects:
+
+```ruby
+@article = ArticleDecorator.find(params[:id])
+```
+
+### When to Decorate Objects
+
+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:
+
+```ruby
+# app/controllers/articles_controller.rb
+class ArticlesController < ApplicationController
+  decorates_assigned :article
+
+  def show
+    @article = Article.find(params[:id])
+  end
+end
+```
+
+The `decorates_assigned :article` bit is roughly equivalent to
+
+```ruby
+def article
+  @decorated_article ||= @article.decorate
+end
+helper_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.
+
+## Testing
+
+Drape supports RSpec, MiniTest::Rails, and Test::Unit, and will add the
+appropriate tests when you generate a decorator.
+
+### RSpec
+
+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:
+
+```ruby
+assigns(:article).should be_decorated
+
+# or, if you want to be more specific
+assigns(:article).should be_decorated_with ArticleDecorator
+```
+
+Note that `model.decorate == model`, so your existing specs shouldn't break when
+you add the decoration.
+
+#### Spork Users
+
+In your `Spork.prefork` block of `spec_helper.rb`, add this:
+
+```ruby
+require 'drape/test/rspec_integration'
+```
+
+### Isolated Tests
+
+In tests, Drape 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:
+
+```ruby
+Drape::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:
+
+```ruby
+Drape::ViewContext.test_strategy :fast do
+  include ApplicationHelper
+end
+```
+
+#### Stubbing Route Helper Functions
+
+If you are writing isolated tests for Drape 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 Drape `helpers` in your tests since they
+inherit from `Drape::TestCase`. If you are using minitest's spec syntax
+without minitest-rails, you can explicitly include the Drape `helpers`:
+
+```ruby
+describe YourDecorator do
+  include Drape::ViewHelpers
+end
+```
+
+Then you can stub the specific route helper functions you need using your
+preferred stubbing technique (this example uses RSpec's `stub` method):
+
+```ruby
+helpers.stub(users_path: '/users')
+```
+
+## Advanced usage
+
+### Shared Decorator Methods
+
+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:
+
+```ruby
+# app/decorators/application_decorator.rb
+class ApplicationDecorator < Drape::Decorator
+# ...
+end
+```
+
+Then modify your decorators to inherit from that `ApplicationDecorator` instead
+of directly from `Drape::Decorator`:
+
+```ruby
+class ArticleDecorator < ApplicationDecorator
+  # decorator methods
+end
+```
+
+### Delegating 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:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  delegate :title, :body
+end
+```
+
+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:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  delegate :title, :body
+  delegate :name, :title, to: :author, prefix: true
+end
+```
+
+From your view template, assuming `@article` is decorated, you could do any of
+the following:
+
+```ruby
+@article.title # Returns the article's `.title`
+@article.body  # Returns the article's `.body`
+@article.author_name  # Returns the article's `author.name`
+@article.author_title # Returns the article's `author.title`
+```
+
+### Adding Context
+
+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:
+
+```ruby
+Article.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:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  decorates_association :author, context: {foo: "bar"}
+end
+```
+
+or, if you want to modify the parent's context, use a lambda that takes a hash
+and returns a new hash:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  decorates_association :author,
+    context: ->(parent_context){ parent_context.merge(foo: "bar") }
+end
+```
+
+### Specifying Decorators
+
+When you're using `decorates_association`, Drape 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:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  decorates_association :author, with: FancyPersonDecorator
+end
+```
+
+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.
+
+### Scoping Associations
+
+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:
+
+```ruby
+class ArticleDecorator < Drape::Decorator
+  decorates_association :comments, scope: :recent
+end
+```
+
+### Proxying Class Methods
+
+If you want to proxy class methods to the wrapped model class, including when
+using `decorates_finders`, Drape 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:
+
+```ruby
+class MySpecialArticleDecorator < Drape::Decorator
+  decorates :article
+end
+```
+
+This is only necessary when proxying class methods.
+
+### Making Models Decoratable
+
+Models get their `decorate` method from the `Drape::Decoratable` module, which
+is included in `ActiveRecord::Base` and `Mongoid::Document` by default. If
+you're [using another
+ORM](https://github.com/drapegem/drape/wiki/Using-other-ORMs) (including
+versions of Mongoid prior to 3.0), or want to decorate plain old Ruby objects,
+you can include this module manually.
+
+## Contributors
+
+Drape was conceived by Jeff Casimir and heavily refined by Steve Klabnik and a
+great community of open source
+[contributors](https://github.com/drapegem/drape/contributors).
+
+### Core Team
+
+* Andrew Emelianenko (andrew@soften-it.com)
+* Jeff Casimir (jeff@jumpstartlab.com)
+* Steve Klabnik (steve@jumpstartlab.com)
+* Vasiliy Ermolovich
+* Andrew Haines