gift_wrap 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37ded86a1243c84591148c1c278126e00eca4c05
-  data.tar.gz: cc8f73fc149fdc246b96b43fa597d250562d429e
+  metadata.gz: bb9527124687cb5c483401325f7327ba25bed6e5
+  data.tar.gz: 9b6dd5ef0e5cedefa05af33f2a9db063f47e258e
 SHA512:
-  metadata.gz: a1b13e46b2b4c1eae2aa13e6b5d3c386ae4c2efd211ca6b015c3c7e86edebd9e96ab8ba069e0dd51c9edf594ae7c6a7b5b9547ef0b11662b439af1300e65df46
-  data.tar.gz: 782ab93cb6d43ffdd15faa770ee183a06f94d56a05a0442c2df21adfce77dca24256ef8d4fbe8152a197f138ca40d9c8e3b27719618b3958cbf244bc318b2469
+  metadata.gz: 56de5b8b0df06343dd0ecfb8a0704f87f252f8dfdb923262e3f32aca6beb220b8c2fcbf890b9a86b59f90988cfc174ad3ebfc3d288528cc8d7e1873831417953
+  data.tar.gz: d047c26b313a8a2fe156ae91626f8f799ee4afdf06d7ecc9840a60b9310730a4c780b04924770254528476d04cb8605e8dc76e2bd0665457b39d3a72d1944b06

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gift_wrap (0.2.0)
+    gift_wrap (1.0.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1 +1,326 @@
 # GiftWrap
+
+A simple Ruby presenter library, for those who enjoy a strong separation of concerns.
+
+
+## What does that mean?
+
+A presenter is just a decorator that is specifically concerned with the presentation layer. GiftWrap provides a simple way to "wrap" a domain entity (e.g. model) for the purpose of decorating it with said presentational logic.
+
+That sort of "view logic" almost never belongs deep in the core code of your domain entities. Yet somehow throwing together classes to house it elsewhere can feel like a chore comprised mostly of boilerplate.
+
+GiftWrap removes this feeling while also being lightweight enough that reading the entire source takes only a few minutes. The core module weighs in at **about 70 lines of code and no depedenecies**. Even the optional helpers for those who use ActiveRecord weigh in at only an additional 30 lines of code, give or take.
+
+Even better, any model logic which is not relevant to presentation or view code is not accidentally accessible on a class implementing `GiftWrap::Presenter` (e.g. persistence code doesn't leak through to templates).
+
+## Other Options
+
+Competition benefits the consumer, and in this case that's you! There is another great gem that does this named [Draper](https://github.com/drapergem/draper), which used to it call itself a "decorator" library, but now focuses on being a tool for "view models". Don't let this indecision in terminology distract from the incredible amount of features and flexibility the project has developed over the last several years.
+
+Another project, [Rectify](https://github.com/andypike/rectify), has a presenter library included in it the same goal as GiftWrap. Rectify's presenters take a more Rails-specific approach, and joins this author in criticising Rails' use of the term "view" for what are just templates.
+
+In both libraries' cases (barring abuse of certain Draper features), separating a domain entity's multi-faceted presentational needs from any internal or persistence logic is achieved just as as well as by GiftWrap. These libraries are equally useful contenders to consider if you like the extras they provide: a large featureset for Draper, additional abstractions in the case of Rectify.
+
+
+## Overview of Use
+
+0. `gem install 'gift_wrap'`
+1. `include GiftWrap::Presenter` in a PORO, a Plain Old Ruby Object.
+2. Call `wrapped_as` with some entity/model name.
+3. Write your own presentational methods in a safe, isolated place.
+
+Optionally, you can delegate methods directly with `unwrap_for` if desired, or use `wrap_association` to keep your presenters referencing each other, instead of letting them meddle in associated core domain models.
+
+
+## What You Get
+
+- A place to isolate all presentational logic related to a particular domain concept or model.
+- An `attributes` method for capturing a user-defined set methods as a Hash.
+- Easy delegation to the underlying model with `unwrap_for`. Use sparingly and with great dicipline.
+- Short-hand to declare unwrapped methods as attributes, via `attribute: true` in the call to `unwrap_for`.
+- The ability to include any methods you define in the usual manner (i.e. `def make_some_noise`) as an attribute.
+- _Optional_ JSON serialization via `ActiveModel::Serializers::JSON`, derived `attributes`.
+- A way to declare an unwrapped method as an "associations" which should be wrapped in their own presenter class.
+- Array-valued associations are built as an array of the association's presenter class.
+
+You might even have one model with two distinct presenters that display the model's attributes in a different manner which are particular to their use in your system's presentation layer.
+
+
+
+## Simple Use
+
+Consider a model class representing a map. A `Map` is of a certain type (physical, political, traffic, etc.), has a defined center point, associated units, a legend and possibly some notes. Some maps show roads, while others do not.
+
+Here is such a class:
+
+```ruby
+class Map
+  attr_reader :type, :center, :units, :legend
+  attr_accessor :notes
+
+  def initialize(type, center, units, legend = :asshole_mapmaker_forgot_legend)
+    @type   = type
+    @center = center
+    @units  = units
+    @notes  = ""
+    @legend = legend
+  end
+
+  def shows_roads?
+    maps_with_roads.include?(type)
+  end
+
+private
+
+  def maps_with_roads
+    ['road', 'traffic', 'political']
+  end
+end
+```
+
+Now consider a minimal presenter which delegates the `type` and `units` methods, and adds a few presentation-specific methods:
+
+```ruby
+class SimpleMapPresenter
+  include GiftWrap::Presenter
+
+  unwrap_for :type
+  unwrap_for :units, attribute: true
+
+  attribute :metric
+
+  def metric
+    metric_map_units.include?(units)
+  end
+
+  def contains_region?(region_name)
+    false # Implementation not important
+  end
+
+  private
+
+  def metric_map_units
+    ['m', 'km']
+  end
+end
+```
+
+The methods `type` and `units` are delegated via `unwrap_for`, with `units` being declated as an attribute.
+
+The additional presentational methods are `contains_region?` and `metric`, with `metric` being declared as an attribute.
+
+Thus a call to `SimpleMapPresenter#attributes` would return a Hash with the keys `:units` and `:metric`, and because they are not explicitly delegated or otherwise referenced, the methods `center`, `legend` and `shows_roads?` on a `Map` object are not accessible on the presenter object.
+
+
+## Explicit Reference of Wrapped Object
+
+In case you would like to internally access the object which your presenter wraps by a domain-appropriate name, the method `wrapped_as` allows for this.
+
+If in the above `Map` class we used this, we could refer to the map by name within instance methods of the presenter. For example, exposing a `has_notes?` method without allowing access to the `notes` method on the map itself:
+
+```ruby
+class SimpleMapPresenter
+  include GiftWrap::Presenter
+
+  wrapped_as :map
+
+  # Previous implementation goes here
+
+  def has_notes?
+    map.notes && map.notes.length > 0
+  end
+end
+```
+
+Or better yet, when providing a default message for missing values, you can keep clunky-looking conditional code such as
+```erb
+<% if map.notes.length > 0 %>
+  <%= map.notes %>
+<% else %>
+  (No notes provided)
+<% end  %>
+```
+out of your templates entirely! Behold:
+
+```ruby
+class SimpleMapPresenter
+  include GiftWrap::Presenter
+
+  wrapped_as :map
+
+  # Previous implementation goes here
+
+  def has_notes?
+    map.notes && map.notes.length > 0
+  end
+
+  def notes
+    has_notes? ? map.notes : "(No notes provided)"
+  end
+end
+```
+
+Then your view template simply becomes
+
+```erb
+<%= map_presenter.notes %>
+```
+
+
+## Associated Objects with their own Presenters
+
+Looking at our simple Map class, we've ignored its `legend` attribute entirely. This is likely expressed as an object with behavior of its own:
+
+```ruby
+class Legend
+  def initialize(colored_regions, colored_lines)
+    @colored_regions  = colored_regions
+    @colored_lines    = colored_lines
+  end
+
+  def region_meaning(color)
+    @colored_regions[color]
+  end
+
+  def line_meaning(color)
+    @colored_lines[color]
+  end
+end
+```
+
+The `Legend` class can be given two hashes which define some of its colors. So for instance, a traffic map might have a legend which is passed colors for land and water regions, and then any colored lines represent traffic congestion:
+
+```ruby
+traffic_map_legend = Legend.new(
+  { beige:  "land",
+    blue:   "water"
+  },
+  { green:  "no congestion",
+    yellow: "light congestion",
+    red:    "heavy congestion",
+    black:  "impassable"
+  })
+```
+
+And accordingly would have its own presenter when it is used in any presentation or view layer of a project:
+
+```ruby
+class LegendPresenter
+  include GiftWrap::Presenter
+
+  unwrap_for :line_meaning
+
+  attribute :red_lines
+
+  def red_lines
+    line_meaning(:red)
+  end
+
+  def yellow_lines
+    line_meaning(:yellow)
+  end
+
+  def green_lines
+    line_meaning(:green)
+  end
+```
+
+And an example of its use:
+
+```ruby
+traffic_legend_presenter = LegendPresenter.new(traffic_map_legend)
+traffic_legend_presenter.red_lines
+# => "heavy congestion"
+traffic_legend_presenter.yellow_lines
+# => "light congestion"
+traffic_legend_presenter.green_lines
+# => "no congestion"
+traffic_legend_presenter.black_lines
+# => NoMethodError: undefined method `black_lines'
+```
+
+A presenter which wraps a `Map` object and which wishes to expose its `Legend` object would do well to instead expose an instance of `LegendPresenter`. It is preferable to keep adjecent code working at the same level of abstraction where possible.
+
+Slavishly re-implementing a method with `def legend` only to return an instance of `LegendPresenter` seems a bit boilerplate, so GiftWrap has a convenience for this:
+
+```ruby
+class LegendaryMapPresenter
+  include GiftWrap::Presenter
+
+  unwrap_for :type, :units
+
+  wrap_association :legend, with: LegendPresenter
+
+  def metric?
+    metric_map_units.include?(units)
+  end
+
+  private
+
+  def metric_map_units
+    ['m', 'km']
+  end
+end
+```
+
+Unlike the `SimpleMapPresenter`, this version has a `legend` method which performs this wrapping for us by calling `wrap_association` and passing the class `LegendPresenter` in the `:with` keyword.
+
+## Customizing Associated Presenters
+
+If the name `legend` was for some reason not desirable, there is no need for the method name exposed on the presenter to be the same of that on the wrapped object. Specifying the association's method name is just another keyword argument in the call to `wrap_association`. If the above class instead had
+```ruby
+wrap_association :legend, with: LegendPresenter, as: :roflcopter
+```
+Then the associated `Legend`, wrapped in a `LegendPresenter`, would be accessible via `map_presenter.roflcopter` instead of `map_presenter.legend`.
+
+Association Presenters can also be **specified on a per-instance basis**, for flexible modification of presentational logic. So if we were malicious map makers and gave a traffic map legend for which every line color meant "no congestion", we could write such a class:
+
+```ruby
+class MisleadingLegendPresenter
+  include GiftWrap::Presenter
+
+  unwrap_for :line_meaning
+
+  def red_lines
+    "no congestion"
+  end
+
+  def yellow_lines
+    "no congestion"
+  end
+
+  def green_lines
+    "no congestion"
+  end
+end
+```
+
+And build our presenter for the traffic map as before, but override the presenter for the `legend` association. This is accomplished by an `:associations` keyword that simply maps the association name to the presenter which should be used. So given a traffic map stored in a variable named `map_with_legend` which references our previous `traffic_map_legend` as its legend:
+
+```ruby
+map_presenter = LegendaryMapPresenter.new(map_with_legend, associations: {
+  legend: MisleadingLegendPresenter
+})
+traffic_legend_presenter = map_presenter.legend
+```
+
+The instance-specific presenter will take effect and `traffic_legend_presenter` will act quite differently than before:
+
+```ruby
+traffic_legend_presenter.red_lines
+# => "no congestion"
+traffic_legend_presenter.yellow_lines
+# => "no congestion"
+traffic_legend_presenter.green_lines
+# => "no congestion"
+```
+
+
+## JSON Serialization
+
+**(Implemented, Example Docs Coming Soon)**
+
+
+## ActiveRecord Convenience Module
+
+**(Implemented, Example Docs Coming Soon)**

data/lib/gift_wrap/presenter.rb

@@ -112,11 +112,15 @@ module GiftWrap
         define_method(as) do
           presenter_class = wrapped_association_presenter(as)
           associated      = @wrapped_object.send(association)
-          if associated.respond_to?(:each)
-            associated.map { |assoc| presenter_class.new(assoc, **options) }
-          else
-            presenter_class.new(associated, **options)
-          end
+          memoized_within = "@#{as}"
+          instance_variable_get(memoized_within) ||
+            instance_variable_set(memoized_within,
+              if associated.respond_to?(:each)
+                associated.map { |assoc| presenter_class.new(assoc, **options) }
+              else
+                presenter_class.new(associated, **options)
+              end
+            )
         end
       end
 

data/lib/gift_wrap/version.rb

@@ -1,3 +1,3 @@
 module GiftWrap
-  VERSION = '0.2.0'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gift_wrap
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Paul Kwiatkowski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-27 00:00:00.000000000 Z
+date: 2016-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -157,7 +157,7 @@ files:
 - test/unit/active_record_presenter_test.rb
 - test/unit/configuration_test.rb
 - test/unit/presenter_test.rb
-homepage: https://github.com/swifthand/adalog
+homepage: https://github.com/swifthand/gift_wrap
 licenses:
 - Revised BSD, see LICENSE.md
 metadata: {}