RubyGems - decent_exposure - Versions diffs - 0.2.0 → 0.2.1 - Mend

decent_exposure 0.2.0 → 0.2.1

Files changed (7) hide show

data/README.html +96 -0
data/README.md +24 -0
data/VERSION +1 -1
data/lib/decent_exposure.rb +14 -7
data/rails/init.rb +7 -1
data/spec/lib/decent_exposure_spec.rb +110 -31
metadata +14 -2

data/README.html ADDED

@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC
+    "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
+    "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
+<html xmlns:svg='http://www.w3.org/2000/svg' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>
+<head><meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' /><title>DecentExposure</title></head>
+<body>
+<h1 id='decentexposure'>DecentExposure</h1>
+<p><em>Copying over instance variables is bad, mmm-kay?</em></p>
+<p>DecentExposure helps you program to an interface, rather than an implementation in your Rails controllers.</p>
+<p>Sharing state via instance variables in controllers promotes close coupling with views. DecentExposure gives you a declarative manner of exposing an interface to the state that controllers contain, thereby decreasing coupling and improving your testability and overall design.</p>
+<h2 id='installation'>Installation</h2>
+<pre><code>gem install decent_exposure</code></pre>
+<p>Configure your application to use it:</p>
+<p>In <code>config/environment.rb</code>:</p>
+<pre><code>config.gem &#39;decent_exposure&#39;</code></pre>
+<h2 id='the_particulars'>The Particulars</h2>
+<p><code>expose</code> creates a method with the given name, evaluates the provided block (or intuits a value when no block is passed) and memoizes the result. This method is then declared as a <code>helper_method</code> so that views may have access to it and is made unroutable as an action.</p>
+<h2 id='examples'>Examples</h2>
+<h3 id='in_your_controllers'>In your controllers</h3>
+<p>When no block is given, <code>expose</code> attempts to intuit which resource you want to acquire:</p>
+<pre><code># Category.find(params[:category_id] || params[:id])
+expose(:category)</code></pre>
+<p>As the example shows, the symbol passed is used to guess the class name of the object you want an instance of. Almost every controller has one of these. In the RESTful controller paradigm, you might use this in <code>#show</code>, <code>#edit</code>, <code>#update</code> or <code>#destroy</code>.</p>
+<p>In the slightly more complicated scenario, you need to find an instance of an object which doesn&#8217;t map cleanly to <code>Object#find</code>:</p>
+<pre><code>expose(:product){ category.products.find(params[:id]) }</code></pre>
+<p>In the RESTful controller paradigm, you&#8217;ll again find yourself using this in <code>#show</code>, <code>#edit</code>, <code>#update</code> or <code>#destroy</code>.</p>
+<p>When the code has become complex enough to surpass a single line (and is not appropriate to extract into a model method), use the <code>do...end</code> style of block:</p>
+<pre><code>expose(:associated_products) do
+  product.associated.tap do |associated_products|
+    present(associated_products, :with =&gt; AssociatedProductPresenter)
+  end
+end</code></pre>
+<h3 id='in_your_views'>In your views</h3>
+<p>Use the product of those assignments like you would an instance variable or any other method you might normally have access to:</p>
+<pre><code>= render bread_crumbs_for(category)
+%h3#product_title= product.title
+= render product
+%h3 Associated Products
+%ul
+  - associated_products.each do |associated_product|
+  %li= link_to(associated_product.title,product_path(associated_product))</code></pre>
+<h3 id='custom_defaults'>Custom defaults</h3>
+<p>DecentExposure provides opinionated default logic when <code>expose</code> is invoked without a block. It&#8217;s possible, however, to override this with your own custom default logic by passing a block accepting a single argument to the <code>default_exposure</code> method inside of a controller. The argument will be the string or symbol passed in to the <code>expose</code> call.</p>
+<pre><code>class MyController &lt; ApplicationController
+  default_exposure do |name|
+    ObjectCache.load(name.to_s)
+  end
+end</code></pre>
+<p>The given block will be invoked in the context of a controller instance. It is possible to provide a custom default for a descendant class without disturbing its ancestor classes in an inheritance heirachy.</p>
+<p><strong>Caveat</strong>: Note that the simplest way to provide custom default <code>expose</code> logic for all of your controllers is to invoke <code>default_exposure</code> inside of <code>ApplicationController</code>. Due to the order of Rails&#8217; initialization logic, na&#239;ve attempts to invoke it in <code>ActionController::Base</code> will have no affect. Use an initializer if you need this behavior.</p>
+<h2 id='beware'>Beware</h2>
+<p>This is an exceptionally simple tool, which provides a solitary solution. It must be used in conjunction with solid design approaches (&#8220;Program to an interface, not an implementation.&#8221;) and accepted best practices (e.g. Fat Model, Skinny Controller). In itself, it won&#8217;t heal a bad design. It is meant only to be a tool to use in improving the overall design of a Ruby on Rails system and moreover to provide a standard implementation for an emerging best practice.</p>
+<h2 id='development'>Development</h2>
+<h3 id='running_specs'>Running specs</h3>
+<p><code>DecentExposure</code> has been developed with the philosophy that Ruby developers shouldn&#8217;t force their choice in RubyGems package managers on people consuming their code. As a side effect of that, if you attempt to run the specs on this application, you might get <code>no such file to load</code> errors. The short answer is that you can <code>export RUBYOPT=&#39;rubygems&#39;</code> and be on about your way (for the long answer, see Ryan Tomayko&#8217;s <a href='http://tomayko.com/writings/require-rubygems-antipattern'>excellent treatise</a> on the subject).</p>
+<h3 id='documentation_todo'>Documentation TODO</h3>
+<ul>
+<li>walk-through of an actual implementation (using an existing, popular OSS Rails app as an example refactor).</li>
+</ul>
+</body></html>

data/README.md CHANGED

@@ -76,6 +76,30 @@ other method you might normally have access to:
       - associated_products.each do |associated_product|
       %li= link_to(associated_product.title,product_path(associated_product))
+### Custom defaults
+DecentExposure provides opinionated default logic when `expose` is invoked without
+a block. It's possible, however, to override this with your own custom default
+logic by passing a block accepting a single argument to the `default_exposure`
+method inside of a controller. The argument will be the string or symbol passed
+in to the `expose` call.
+    class MyController < ApplicationController
+      default_exposure do |name|
+        ObjectCache.load(name.to_s)
+      end
+    end
+The given block will be invoked in the context of a controller instance. It is
+possible to provide a custom default for a descendant class without disturbing
+its ancestor classes in an inheritance heirachy.
+**Caveat**: Note that the simplest way to provide custom default `expose` logic
+for all of your controllers is to invoke `default_exposure` inside of
+`ApplicationController`. Due to the order of Rails' initialization logic,
+attempts to invoke it in `ActionController::Base` will have no affect. Use an
+initializer if you need this behavior.
 Beware
 ------

data/VERSION CHANGED

	@@ -1 +1 @@
1	- 0.2.0
1	+ 0.2.1

data/lib/decent_exposure.rb CHANGED

@@ -1,21 +1,28 @@
 module DecentExposure
+  def inherited(klass)
+    closured_exposure = default_exposure
+    klass.class_eval do
+      default_exposure(&closured_exposure)
+    end
+  end
+  def default_exposure(&block)
+    @default_exposure = block if block_given?
+    @default_exposure
+  end
   def expose(name, &block)
+    closured_exposure = default_exposure
     define_method name do
       @_resources       ||= {}
       @_resources[name] ||= if block_given?
         instance_eval(&block)
       else
-        _class_for(name).find(params["#{name}_id"] || params['id'])
+        instance_exec(name, &closured_exposure)
       end
     end
     helper_method name
     hide_action name
   end
   alias let expose
-  private
-  def _class_for(name)
-    name.to_s.classify.constantize
-  end
 end

data/rails/init.rb CHANGED

@@ -4,4 +4,10 @@ rescue LoadError
   require 'decent_exposure' # From gem
 end
-ActionController::Base.extend(DecentExposure)
+ActionController::Base.class_eval do
+  extend DecentExposure
+  default_exposure do |name|
+    model_class = name.to_s.classify.constantize
+    model_class.find(params["#{name}_id"] || params['id'])
+  end
+end

data/spec/lib/decent_exposure_spec.rb CHANGED

@@ -4,11 +4,28 @@ class Quacker
   extend DecentExposure
   def self.helper_method(*args); end
   def self.hide_action(*args); end
-  def self.find(*args); end
   def memoizable(*args); args; end
-  def params; {'proxy_id' => 42}; end
   expose(:proxy)
-  expose(:quack){ memoizable('quack!') }
+end
+module ActionController
+  class Base
+    def self.helper_method(*args); end
+    def self.hide_action(*args); end
+    def params; {'resource_id' => 42}; end
+  end
+end
+require File.join(File.dirname(__FILE__), '..', '..', 'rails', 'init.rb')
+class MyController < ActionController::Base
+end
+class Resource
+  def self.find(*args); end
+end
+class Widget
+  def self.find(*args); end
 end
 describe DecentExposure do
@@ -22,7 +39,7 @@ describe DecentExposure do
     let(:instance){ Quacker.new }
     it "creates a method with the given name" do
-      Quacker.new.methods.map{|m| m.to_s}.should include('quack')
+      Quacker.new.methods.map{|m| m.to_s}.should include('proxy')
     end
     it "prevents the method from being a callable action" do
@@ -40,7 +57,12 @@ describe DecentExposure do
       end
     end
-    it "returns the value of the method" do
+    it "returns the result of the exposed block from the method" do
+      Quacker.stubs(:hide_action)
+      Quacker.stubs(:helper_method)
+      Quacker.class_eval do
+        expose(:quack){ memoizable('quack!') }
+      end
       instance.quack.should == %w(quack!)
     end
@@ -50,46 +72,103 @@ describe DecentExposure do
       instance.quack
     end
-    context "when no block is given" do
-      before do
-        instance.stubs(:_class_for).returns(Quacker)
+    context "when specifying custom default behavior" do
+      before(:all) do
+        class ::DuckController
+          extend DecentExposure
+          def self.helper_method(*args); end
+          def self.hide_action(*args); end
+          def params; end
+          default_exposure {"default value"}
+          expose(:quack)
+        end
+      end
+      it "uses that behavior when no block is given" do
+        DuckController.new.quack.should == "default value"
       end
-      it "attempts to guess the class of the resource to expose" do
-        instance.expects(:_class_for).with(:proxy).returns(Quacker)
-        instance.proxy
+      it "passes the name given to #expose into the block" do
+        DuckController.class_eval do
+          default_exposure {|name| "downy #{name}"}
+          expose :feathers
+        end
+        DuckController.new.feathers.should == "downy feathers"
       end
-      it "calls find with {resource}_id on the resources class" do
-        Quacker.expects(:find).with(42)
-        instance.proxy
+    end
+  end
+  context "within Rails" do
+    let(:controller) {ActionController::Base.new}
+    let(:resource){ 'resource' }
+    let(:resource_class_name){ 'Resource' }
+    before do
+      resource.stubs(:to_s => resource, :classify => resource_class_name)
+      resource_class_name.stubs(:constantize => Resource)
+    end
+    it "extends ActionController::Base" do
+      ActionController::Base.respond_to?(:expose).should == true
+    end
+    context "by default" do
+      it "calls find with params[:resource_id] on the resource's class" do
+        name = resource
+        Resource.expects(:find).with(42)
+        ActionController::Base.class_eval do
+          expose name
+        end
+        controller.resource
       end
-      context "and there is no {resource}_id" do
+      context "or, when there is no :resource_id in params" do
         before do
-          Quacker.class_eval do
+          ActionController::Base.class_eval do
             def params; {'id' => 24}; end
           end
         end
-        it "calls find with params[:id] on the resources class" do
-          Quacker.expects(:find).with(24)
-          instance.proxy
+        it "calls find with params[:id] on the resource's class" do
+          Resource.expects(:find).with(24)
+          controller.resource
         end
       end
     end
-  end
-  describe '#_class_for' do
-    let(:name){ 'quacker' }
-    let(:classified_name){ 'Quacker' }
+    let(:widget){ 'widget' }
+    let(:widget_class_name){ 'Widget' }
     before do
-      name.stubs(:to_s => name, :classify => classified_name)
-      classified_name.stubs(:constantize => Quacker)
+      widget.stubs(:to_s => widget, :classify => widget_class_name)
+      widget_class_name.stubs(:constantize => Widget)
+    end
+    let(:my_controller) {MyController.new}
+    it "works in descendant controllers" do
+      name = widget
+      Widget.expects(:find).with(123).returns('a widget')
+      MyController.class_eval do
+        def params; {'id' => 123} end
+        expose name
+      end
+      my_controller.widget.should == 'a widget'
     end
-    it 'retrieves a string representation of the class name' do
-      name.expects(:classify).returns(classified_name)
-      Quacker.send(:_class_for,name)
+    it "allows overridden default in descendant controllers" do
+      MyController.class_eval do
+        default_exposure {|name| name.to_s}
+        expose :overridden
+      end
+      my_controller.overridden.should == 'overridden'
     end
-    it 'returns the string representation of the name as a constant' do
-      classified_name.expects(:constantize)
-      Quacker.send(:_class_for,name)
+    it "preserves default in ancestors" do
+      name = widget
+      Widget.stubs(:find).returns('preserved')
+      ActionController::Base.class_eval do
+        expose name
+      end
+      controller.widget.should == 'preserved'
     end
   end
 end

metadata CHANGED

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decent_exposure
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Stephen Caudill
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2010-01-31 00:00:00 -05:00
+date: 2010-02-19 00:00:00 -05:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -23,6 +23,16 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.2.9
     version:
+- !ruby/object:Gem::Dependency
+  name: mocha
+  type: :development
+  version_requirement:
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.8
+    version:
 description: "\n      DecentExposure helps you program to an interface, rather than an implementation\n      in your Rails controllers.  The fact of the matter is that sharing state\n      via instance variables in controllers promotes close coupling with views.\n      DecentExposure gives you a declarative manner of exposing an interface to the\n      state that controllers contain and thereby decreasing coupling and\n      improving your testability and overall design.\n    "
 email: scaudill@gmail.com
 executables: []
@@ -30,6 +40,7 @@ executables: []
 extensions: []
 extra_rdoc_files:
+- README.html
 - README.md
 files:
 - COPYING
@@ -37,6 +48,7 @@ files:
 - VERSION
 - lib/decent_exposure.rb
 - rails/init.rb
+- README.html
 has_rdoc: true
 homepage: http://github.com/voxdolo/decent_exposure
 licenses: []