RubyGems - decent_exposure - Versions diffs - 1.0.0.rc1 → 1.0.0.rc2 - Mend

decent_exposure 1.0.0.rc1 → 1.0.0.rc2

Files changed (7) hide show

data/README.html +119 -0
data/README.md +62 -45
data/VERSION +1 -1
data/lib/decent_exposure/default_exposure.rb +9 -27
data/spec/lib/decent_exposure_spec.rb +1 -1
data/spec/lib/rails_integration_spec.rb +27 -2
metadata +17 -7

data/README.html ADDED Viewed

@@ -0,0 +1,119 @@
+<html>
+  <head>
+    <style type='text/css'>
+      body{ width:50em; }
+      pre{ margin-left:2em; }
+    </style>
+  </head>
+  <body>
+<h1 id='decentexposure'>DecentExposure</h1>
+<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 Rails 2.X application to use it:</p>
+<p>In <code>config/environment.rb</code>:</p>
+<pre><code>config.gem &#39;decent_exposure&#39;</code></pre>
+<p>When used in Rails 3:</p>
+<p>In <code>Gemfile</code>:</p>
+<pre><code>gem &#39;decent_exposure&#39;</code></pre>
+<h2 id='examples'>Examples</h2>
+<h3 id='a_full_example'>A full example</h3>
+<p>The wiki has a full example of <a href='http://github.com/voxdolo/decent_exposure/wiki/Examples'>converting a classic-style Rails controller</a>.</p>
+<h3 id='in_your_controllers'>In your controllers</h3>
+<p>When no block is given, <code>expose</code> attempts to determine which resource you want to acquire. When <code>params</code> contains <code>:category_id</code> or <code>:id</code>, a call to:</p>
+<pre><code>expose(:category)</code></pre>
+<p>Would result in the following <code>ActiveRecord#find</code>:</p>
+<pre><code>Category.find(params[:category_id]||params[:id])</code></pre>
+<p>As the example shows, the symbol passed is used to guess the class name of the object (and potentially the <code>params</code> key to find it with) you want an instance of.</p>
+<p>Should <code>params</code> not contain an identifiable <code>id</code>, a call to:</p>
+<pre><code>expose(:category)</code></pre>
+<p>Will instead attempt to build a new instance of the object like so:</p>
+<pre><code>Category.new(params[:category])</code></pre>
+<p>If you define a collection with a pluralized name of the singular resource, <code>decent_exposure</code> will attempt to use it to scope its calls from. Let&#8217;s take the following scenario:</p>
+<pre><code>class ProductsController &lt; ApplicationController
+  expose(:category)
+  expose(:products) { category.products }
+  expose(:product)
+end</code></pre>
+<p>The <code>product</code> resource would scope from the <code>products</code> collection via a fully-expanded query equivalent to this:</p>
+<pre><code>Category.find(params[:category_id]).products.find(params[:id])</code></pre>
+<p>or (depending on the contents of the <code>params</code> hash) this:</p>
+<pre><code>Category.find(params[:category_id]).products.new(params[:product])</code></pre>
+<p>In the straightforward case, the three exposed resources above provide for access to both the primary and ancestor resources in a way usable across all 7 actions in a typicall Rails-style RESTful controller.</p>
+<h4 id='a_note_on_style'>A Note on Style</h4>
+<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 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>
+<h2 id='beware'>Beware</h2>
+<p>This is a 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>
+  </body>
+</html>

data/README.md CHANGED Viewed

@@ -1,15 +1,11 @@
-DecentExposure
-==============
-_Copying over instance variables is bad, mmm-kay?_
-DecentExposure helps you program to an interface, rather than an implementation in
+`decent_exposure` helps you program to an interface, rather than an implementation in
 your Rails controllers.
 Sharing state via instance variables in controllers promotes close coupling with
-views. DecentExposure gives you a declarative manner of exposing an interface to the
+views. `decent_exposure` 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.
+testability and overall design. I elaborate on this approach in [A Diatribe on
+Maintaining State][diatribe].
 Installation
 ------------
@@ -29,37 +25,61 @@ In `Gemfile`:
     gem 'decent_exposure'
-The Particulars
----------------
-`expose` 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 `helper_method` so that views may have access to it and is
-made unroutable as an action.
 Examples
 --------
+### A full example
+The wiki has a full example of [converting a classic-style Rails
+controller][converting].
 ### In your controllers
-When no block is given, `expose` attempts to intuit which resource you want to
-acquire:
+When no block is given, `expose` attempts to determine which resource you want
+to acquire. When `params` contains `:category_id` or `:id`, a call to:
-    # Category.find(params[:category_id] || params[:id])
     expose(:category)
+Would result in the following `ActiveRecord#find`:
+    Category.find(params[:category_id]||params[:id])
 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 `#show`, `#edit`, `#update`
-or `#destroy`.
+object (and potentially the `params` key to find it with) you want an instance
+of.
+Should `params` not contain an identifiable `id`, a call to:
+    expose(:category)
+Will instead attempt to build a new instance of the object like so:
+    Category.new(params[:category])
+If you define a collection with a pluralized name of the singular resource,
+`decent_exposure` will attempt to use it to scope its calls from. Let's take the
+following scenario:
+    class ProductsController < ApplicationController
+      expose(:category)
+      expose(:products) { category.products }
+      expose(:product)
+    end
+The `product` resource would scope from the `products` collection via a
+fully-expanded query equivalent to this:
+    Category.find(params[:category_id]).products.find(params[:id])
-In the slightly more complicated scenario, you need to find an instance of an
-object which doesn't map cleanly to `Object#find`:
+or (depending on the contents of the `params` hash) this:
-    expose(:product){ category.products.find(params[:id]) }
+    Category.find(params[:category_id]).products.new(params[:product])
-In the RESTful controller paradigm, you'll again find yourself using this in
-`#show`, `#edit`, `#update` or `#destroy`.
+In the straightforward case, the three exposed resources above provide for
+access to both the primary and ancestor resources in a way usable across all 7
+actions in a typicall Rails-style RESTful controller.
+#### A Note on Style
 When the code has become complex enough to surpass a single line (and is not
 appropriate to extract into a model method), use the `do...end` style of block:
@@ -85,11 +105,11 @@ other method you might normally have access to:
 ### 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.
+`decent_exposure` provides opinionated default logic when `expose` is invoked without
+a block. It's possible, however, to override this with 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|
@@ -104,11 +124,11 @@ its ancestor classes in an inheritance heirachy.
 Beware
 ------
-This is an exceptionally simple tool, which provides a solitary solution. It
-must be used in conjunction with solid design approaches ("Program to an
-interface, not an implementation.") and accepted best practices (e.g. Fat Model,
-Skinny Controller). In itself, it won'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
+This is a simple tool, which provides a solitary solution. It must be used in
+conjunction with solid design approaches ("Program to an interface, not an
+implementation.") and accepted best practices (e.g. Fat Model, Skinny
+Controller). In itself, it won'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.
 Development
@@ -116,16 +136,13 @@ Development
 ### Running specs
-`DecentExposure` has been developed with the philosophy that Ruby developers shouldn't
+`decent_exposure` has been developed with the philosophy that Ruby developers shouldn'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 `no such file to load` errors.  The short answer is that you can
 `export RUBYOPT='rubygems'` and be on about your way (for the long answer, see
-Ryan Tomayko's [excellent
-treatise](http://tomayko.com/writings/require-rubygems-antipattern) on the
-subject).
-### Documentation TODO
+Ryan Tomayko's [excellent treatise][treatise] on the subject).
-* walk-through of an actual implementation (using an existing, popular OSS Rails
-app as an example refactor).
+[treatise]: http://tomayko.com/writings/require-rubygems-antipattern
+[converting]: http://github.com/voxdolo/decent_exposure/wiki/Examples
+[diatribe]: http://blog.voxdolo.me/a-diatribe-on-maintaining-state.html

data/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 1.0.0.~~rc1~~
1	+ 1.0.0.rc2

data/lib/decent_exposure/default_exposure.rb CHANGED Viewed

@@ -4,39 +4,21 @@ module DecentExposure
       klass.extend(DecentExposure)
       klass.superclass_delegating_accessor(:_default_exposure)
       klass.default_exposure do |name|
-        self._resource_name = name.to_s
+        collection = name.to_s.pluralize
+        if respond_to?(collection) && collection != name.to_s && send(collection).respond_to?(:scoped)
+          proxy = send(collection)
+        else
+          proxy = name.to_s.classify.constantize
+        end
         if id = params["#{name}_id"] || params[:id]
-          _proxy.find(id).tap do |r|
+          proxy.find(id).tap do |r|
             r.attributes = params[name] unless request.get?
           end
         else
-          _proxy.new(params[name])
-        end
-      end
-    end
-    private
-    attr_accessor :_resource_name
-    def _resource_class
-      _resource_name.classify.constantize
-    end
-    def _collection_name
-      _resource_name.pluralize
-    end
-    def _proxy
-      _collection.respond_to?(:scoped) ? _collection : _resource_class
-    end
-    def _collection
-      unless self.class.method_defined?(_collection_name)
-        self.class.expose(_collection_name) do
-          _collection_name.classify.constantize.scoped({})
+          proxy.new(params[name])
         end
       end
-      send(_collection_name)
     end
   end
 end

data/spec/lib/decent_exposure_spec.rb CHANGED Viewed

@@ -20,7 +20,7 @@ describe DecentExposure do
     let(:instance) { controller.new }
     it 'creates a method with the given name' do
-      instance.methods.should include('resource')
+      instance.methods.should include(:resource)
     end
     it 'prevents the method from being a callable action' do

data/spec/lib/rails_integration_spec.rb CHANGED Viewed

@@ -9,6 +9,12 @@ class Resource
   def initialize(*args); end
 end
+class Equipment
+  def self.scoped(opts); self; end
+  def self.find(*args); end
+  def initialize(*args); end
+end
 describe "Rails' integration:", DecentExposure do
   let(:controller) { Class.new(ActionController::Base) }
   let(:instance) { controller.new }
@@ -65,9 +71,9 @@ describe "Rails' integration:", DecentExposure do
     end
     context 'when no collection method exists' do
-      it 'creates a collection method to scope from' do
+      it 'operates directly on the class' do
+        Resource.should_receive(:find)
         instance.resource
-        instance.methods.should include('resources')
       end
     end
@@ -128,3 +134,22 @@ describe "Rails' integration:", DecentExposure do
     end
   end
 end
+describe "Rails' integration:", DecentExposure do
+  let(:controller) { Class.new(ActionController::Base) }
+  let(:instance) { controller.new }
+  let(:request) { mock(:get? => true) }
+  let(:params) { HashWithIndifferentAccess.new(:resource_id => 42) }
+  before do
+    controller.expose(:equipment)
+    instance.stubs(:request).returns(request)
+    instance.stubs(:params).returns(params)
+  end
+  context 'when collection name is same as resource name' do
+    it 'does not create a collection method' do
+      instance.equipment
+      instance.methods.should include(:equipment)
+      instance.methods.should_not include(:equipments)
+    end
+  end
+end

metadata CHANGED Viewed

@@ -6,8 +6,8 @@ version: !ruby/object:Gem::Version
   - 1
   - 0
   - 0
-  - rc1
-  version: 1.0.0.rc1
+  - rc2
+  version: 1.0.0.rc2
 platform: ruby
 authors:
 - Stephen Caudill
@@ -16,27 +16,29 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2010-07-16 00:00:00 -04:00
+date: 2010-12-02 00:00:00 -05:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         segments:
         - 1
-        - 2
-        - 9
-        version: 1.2.9
+        - 3
+        - 0
+        version: 1.3.0
   type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency
   name: mocha
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
@@ -51,6 +53,7 @@ dependencies:
   name: actionpack
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
@@ -66,6 +69,7 @@ executables: []
 extensions: []
 extra_rdoc_files:
+- README.html
 - README.md
 files:
 - COPYING
@@ -75,6 +79,10 @@ files:
 - lib/decent_exposure/default_exposure.rb
 - lib/decent_exposure/railtie.rb
 - rails/init.rb
+- README.html
+- spec/helper.rb
+- spec/lib/decent_exposure_spec.rb
+- spec/lib/rails_integration_spec.rb
 has_rdoc: true
 homepage: http://github.com/voxdolo/decent_exposure
 licenses: []
@@ -85,6 +93,7 @@ rdoc_options:
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
@@ -92,6 +101,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ">"
     - !ruby/object:Gem::Version
@@ -103,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubyforge_project:
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key:
 specification_version: 3
 summary: A helper for creating declarative interfaces in controllers