display_case 0.0.0 → 0.0.1

data/README.md

@@ -1,4 +1,73 @@
 display_case
 ============
 
-An implementation of the Exhibit pattern, as described in Objects on Rails
+An implementation of the Exhibit pattern, as described in Objects on Rails
+
+Description
+-----------
+If the Model is concerned with storing and manipulating business data, and the View is concerned with displaying it, you can think of the Exhibit as standing between them deciding which data to show, and in what order. It may also provide some extra presentation-specific information (such as the specific URLs for related resources) which the business model has no knowledge of by itself.
+
+The Exhibit object is so named because it is like a museum display case for an artifact or a work of art. It does not obscure any of the features of the object being presented. Rather, it tries showcase the object in the best light to a human audience, while also presenting meta-information about the object and cross-references to other objects in the museum's collection.
+
+Technically, exhibit objects are a type of Decorator specialized for presenting models to an end user. 
+
+For the purposes of clarity, here's a rundown of the essential characteristics of an Exhibit object.
+
+An Exhibit object:
+
+1. **Wraps a single model instance.**
+1. **Is a true Decorator.** All unrecognized messages are passed through to the underlying object. This facilitates a gradual migration to the use of Exhibits to encapsulate presentation knowledge, since they can be layered onto models without any change to the existing views. It also enables multiple Exhibits to be layered onto an object, each handling different aspects of presentation.
+1. **Brings together a model and a context.** Exhibits need a reference to a "context" object—either a controller or a view context—in order to be able to render templates as well as construct URLs for the object or related resources.
+1. **Encapsulates decisions about how to render an object.** The tell-tale of an Exhibit is telling an object "render yourself", rather than explicitly rendering a template and passing the object in as an argument.
+1. **May modify the behavior of an object.** For instance, an Exhibit might impose a scope on a `Blog#entries` association which only returns entries that are visible to the current user (as determined from the Exhibit's controller context). Or it might reformat the return value of a `#social_security_number` method to include dashes and have all but the last four digits obscured: `***-**-5678`.
+
+Installation
+------------
+`gem 'display_case'` in your Gemfile if you're using Bundler, or `gem install display_case` from the command line.
+
+Usage
+-----
+Your exhibits will look something like this:
+``` ruby
+# app/exhibits/league_exhibit.rb
+
+class LeagueExhibit < Exhibit
+  def self.applicable_to?(object)
+    object.class.name == 'League'
+  end
+  
+  def render_icon(template)
+    template.render(partial: 'leagues/icon', locals: {league: self})
+  end
+end
+```
+
+Then in your controller, where you're instantiating a League, wrap it in a call to the `exhibit` helper to turn get the Exhibited object, rather than the raw one.
+``` ruby
+# app/controllers/leagues_controller.rb
+class LeaguesController < ApplicationController
+  # ...
+  def index
+    # display_case automatically wraps the individual objects contained in 
+    # an Enumerable or ActiveRecord::Relation collections
+    @leagues = exhibit(League.all) 
+  end
+  
+  def show
+    # of course it will also wrap your individual objects
+    @league = exhibit(League.find(params[:id]))
+  end
+end
+```
+
+Finally, in your view, you can use your Exhibit:
+```
+<!-- app/views/leagues/index.html.erb -->
+<% @leagues.each do |league| %> 
+  <%= league.render_icon(self) %> <!-- self is this "template", the parameter to the method we defined in LeagueExhibit -->
+<% end %>
+```
+
+Configuration
+-------------
+Because Rails lazily-loads files, in development mode DisplayCase will search /app/exhibits to load the Exhibits found there. If your Exhibits are elsewhere, you can set `DisplayCase.definition_file_paths = ['list/of/directories', 'to/find/exhibits']` in your config/environments/development.rb.

data/lib/display_case/exhibit.rb

@@ -1,20 +1,21 @@
 require 'delegate'
 require 'active_support/core_ext'
+require 'display_case/railtie' if defined?(Rails)
 
 class Exhibit < SimpleDelegator
+  @@exhibits = []
+  
   def self.exhibits
-    [
-     EnumerableExhibit,
-     BlogExhibit,
-     TextPostExhibit,
-     PicturePostExhibit,
-     LinkExhibit,
-     TagListExhibit
-    ]
+    @@exhibits
+  end
+  
+  def self.inherited(child)
+    @@exhibits << child
   end
 
   def self.exhibit(object, context)
     return object if exhibited_object?(object)
+    Rails.logger.debug "Registered exhibits: #{@@exhibits}"
     Rails.logger.debug "Exhibiting #{object.inspect}"
     Rails.logger.debug "Exhibit context: #{context}"
     object = Exhibited.new(object, context)

data/lib/display_case/find_definitions.rb

@@ -0,0 +1,24 @@
+module DisplayCase
+  class << self
+    # An Array of strings specifying locations that should be searched for
+    # exhibit classes and definitions. By default, "/app/exhibits" will be searched and
+    # existing file will be loaded.
+    attr_accessor :definition_file_paths
+  end
+
+  self.definition_file_paths = %w(app/exhibits)
+
+  def self.find_definitions
+    absolute_definition_file_paths = definition_file_paths.map {|path| File.expand_path(path) }
+
+    absolute_definition_file_paths.uniq.each do |path|
+      load("#{path}.rb") if File.exists?("#{path}.rb")
+
+      if File.directory? path
+        Dir[File.join(path, '**', '*.rb')].sort.each do |file|
+          load file
+        end
+      end
+    end
+  end
+end

data/lib/display_case/railtie.rb

@@ -0,0 +1,7 @@
+module DisplayCase
+  class Railtie < Rails::Railtie
+    config.to_prepare do
+      DisplayCase.find_definitions if Rails.env.development?
+    end    
+  end
+end

data/lib/display_case.rb

@@ -0,0 +1,5 @@
+require_relative 'display_case/exhibit'
+require_relative 'display_case/enumerable_exhibit'
+require_relative 'display_case/exhibits_helper'
+require_relative 'display_case/find_definitions'
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: display_case
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-17 00:00:00.000000000Z
+date: 2012-05-23 00:00:00.000000000Z
 dependencies: []
 description: An implementation of the Exhibit pattern, as described in Objects on
   Rails
@@ -22,6 +22,8 @@ files:
 - lib/display_case/enumerable_exhibit.rb
 - lib/display_case/exhibit.rb
 - lib/display_case/exhibits_helper.rb
+- lib/display_case/find_definitions.rb
+- lib/display_case/railtie.rb
 - lib/display_case.rb
 - LICENSE
 - README.md