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

decent_exposure 1.0.0.rc1 → 1.0.0.rc2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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