roar-rails 0.0.7 → 0.0.8

data/CHANGES.markdown

@@ -1,3 +1,7 @@
+h2. 0.0.8
+
+* Added `#represents` to configure consuming and rendering on controller class layer. This also calls `respond_to`.
+
 h2. 0.0.7
 
 * Introduce `:represent_with` and `:represent_items_with` for `#respond_with`. In turn, deprecate the old behaviour since it will change in 1.0.

data/README.markdown

@@ -2,6 +2,8 @@
 
 _Makes using Roar's representers in your Rails app fun._
 
+Roar is a framework for parsing and rendering REST documents. For a better overview about representers please check the [roar repository](https://github.com/apotonick/roar#roar).
+
 ## Features
 
 * Rendering with responders
@@ -12,6 +14,10 @@ _Makes using Roar's representers in your Rails app fun._
 
 ## Rendering with #respond_with
 
+roar-rails provides a number of baked-in rendering methods.
+
+### Conventional Rendering
+
 Easily render resources using representers with the built-in responder.
 
 ```ruby
@@ -26,21 +32,35 @@ class SingersController < ApplicationController
 end
 ```
 
-Need to use a representer with a different name than your model? Pass it in using the `:represent_with` option:
+The representer name will be infered from the passed model class (e.g. a `Singer` instance gets the `SingerRepresenter`). If the passed model is a collection it will be extended using a representer. The representer name will be computed from the controller name (e.g. a `SingersController` uses the `SingersRepresenter`).
+
+Need to use a representer with a different name than your model? You may always pass it in using the `:represent_with` option:
+
+```ruby
+respond_with singers, :represent_with => MusicianCollectionRepresenter
+end
+```
+
+### Represents Configuration
+
+If you don't want to use conventions or pass representers you can configure them on the class level using `#represents`. This will also call `respond_to` for you.
 
 ```ruby
 class SingersController < ApplicationController
-  include Roar::Rails::ControllerAdditions
-  respond_to :json
+  represents :json, Musician
+```
+This will use the `MusicianRepresenter` for models and `MusiciansRepresenter` for representing collections.
 
-  def show
-    singer = Musician.find_by_id(params[:id])
-    respond_with singer, :represent_with => SingerRepresenter
-  end
-end
+Note that `#represents` also allows fine-tuning.
+
+```ruby
+class SingersController < ApplicationController
+  represents :json, :entity => MusicianRepresenter, :collection => MusicianCollectionRepresenter
 ```
 
-If you don't want to write a dedicated representer for a collection of items (highly recommended, thou) but rather use a representer for each item, use the `+represent_items_with+` option.
+### Old API Support
+
+If you don't want to write a dedicated representer for a collection of items (highly recommended, thou) but rather use a representer for each item, use the `:represent_items_with` option.
 
 ```ruby
 class SingersController < ApplicationController
@@ -96,6 +116,12 @@ singer.
 
 So, `#consume!` helps you figuring out the representer module and reading the incoming document.
 
+Note that it respects settings from `#represents`. It uses the same mechanics known from `#respond_with` to choose a representer.
+
+```ruby
+consume!(singer, :represent_with => MusicianRepresenter)
+```
+
 ## URL Helpers
 
 Any URL helpers from the Rails app are automatically available in representers.

data/lib/roar/rails/controller_additions.rb

@@ -3,23 +3,63 @@ module Roar::Rails
     extend ActiveSupport::Concern
     include ModelMethods
     
+    included do
+      class_attribute :represents_options
+      self.represents_options ||= {}
+    end
+    
+    
     module ClassMethods
       def responder
         Class.new(super).send :include, Roar::Rails::Responder
       end
+      
+      def add_representer_suffix(prefix)
+        "#{prefix}Representer"
+      end
+    
+      def represents(format, options)
+        unless options.is_a?(Hash)
+          model = options
+          options = {
+            :entity     => add_representer_suffix(model.name).constantize,
+            :collection => add_representer_suffix(model.name.pluralize).constantize
+          }
+        end
+        
+        represents_options[format] = options
+        respond_to format
+      end
     end
     
     
-    def consume!(model)
-      format = formats.first  # FIXME: i expected request.content_mime_type to do the job. copied from responder.rb. this will return the wrong format when the controller responds to :json and :xml and the Content-type is :xml (?)
-      extend_with_representer!(model)
+    def consume!(model, options={})
+      format      = formats.first  # FIXME: i expected request.content_mime_type to do the job. copied from responder.rb. this will return the wrong format when the controller responds to :json and :xml and the Content-type is :xml (?)
+      representer = representer_for(format, model, options)
+      extend_with!(model, representer)
       model.send(compute_parsing_method(format), request.body.string) # e.g. from_json("...")
       model
     end
     
+    # Central entry-point for finding the appropriate representer.
+    def representer_for(format, model, options={})
+      options.delete(:represent_with) || representer_name_for(format, model)
+    end
+    
   private
     def compute_parsing_method(format)
       "from_#{format}"
     end
+    
+    def representer_name_for(format, model)  # DISCUSS: should we pass and process options here?
+      if self.class.represents_options[format.to_sym].blank?  # TODO: test to_sym?
+        model_name = model.class.name
+        model_name = controller_path.camelize if model.kind_of?(Array)
+        return self.class.add_representer_suffix(model_name).constantize
+      end
+      
+      return self.class.represents_options[format][:collection] if model.kind_of?(Array)
+      self.class.represents_options[format][:entity]
+    end
   end
 end

data/lib/roar/rails/responder.rb

@@ -1,16 +1,9 @@
 module Roar::Rails
   module ModelMethods
     # DISCUSS: move this into a generic namespace as we could need that in Sinatra as well.
-    def extend_with_representer!(model, representer=nil)
-      representer ||= representer_for_model(model)
+    def extend_with!(model, representer)
       model.extend(representer)
     end
-    
-  private
-    def representer_for_model(model)
-      class_name = model.class.name
-      "#{class_name}Representer".constantize
-    end
   end
   
   module Responder
@@ -18,28 +11,23 @@ module Roar::Rails
     
     # DISCUSS: why THE FUCK is options not passed as a method argument but kept as an internal instance variable in the responder? this is something i will never understand about Rails.
     def display(model, *args)
-      if representer = options.delete(:represent_with)
-        # this is the new behaviour.
-        model.extend(representer) # FIXME: move to method.
+      if representer = options.delete(:represent_items_with)
+        render_items_with(model, representer) # convenience API, not recommended since it's missing hypermedia.
         return super
       end
       
-      
-      representer = options.delete(:with_representer) and ActiveSupport::Deprecation.warn(":with_representer is deprecated and will be removed in roar-rails 1.0. Use :represent_with or :represent_items_with.")
-      representer ||= options.delete(:represent_items_with) # new API.
-      
-      if model.respond_to?(:map!)
-        ActiveSupport::Deprecation.warn("Calling #respond_with with a collection will misbehave in future versions of roar-rails. Use :represent_items_with to get the old behaviour.")
-        
-        model.map! do |m|
-          extend_with_representer!(m, representer)
-          m.to_hash
-        end
-      else
-        extend_with_representer!(model, representer)
-      end
-      
+      representer = controller.representer_for(format, model, options)
+      extend_with!(model, representer)
       super
     end
+    
+  private
+    def render_items_with(collection, representer)
+      collection.map! do |m|  # DISCUSS: i don't like changing the method argument here.
+        extend_with!(m, representer)
+        m.to_hash # FIXME: huh? and what about XML?
+      end
+    end
+    
   end
 end

data/lib/roar/rails/version.rb

@@ -1,5 +1,5 @@
 module Roar
   module Rails
-    VERSION = "0.0.7"
+    VERSION = "0.0.8"
   end
 end

data/test/consume_test.rb

@@ -19,9 +19,59 @@ class ConsumeTest < ActionController::TestCase
     post :consume_json, "{\"name\": \"Bumi\"}", :format => 'json'
     assert_equal singer.to_json, @response.body
   end
-
+  
   def singer(name="Bumi")
     singer = Musician.new(name)
     singer.extend SingerRepresenter
   end
 end
+
+class ConsumeWithConfigurationTest < ConsumeTest
+  include Roar::Rails::TestCase
+  
+  module MusicianRepresenter
+    include Roar::Representer::JSON
+    property :name, :from => :called
+  end
+  
+  
+  class SingersController < ActionController::Base
+    include Roar::Rails::ControllerAdditions
+    respond_to :json
+    represents "json", :entity => MusicianRepresenter
+
+    def consume_json
+      singer = consume!(Singer.new)
+      render :text => singer.to_json
+    end
+  end
+
+  tests SingersController
+  
+  test "#consume uses #represents config to parse incoming document" do
+    post :consume_json, "{\"name\": \"Bumi\"}", :format => :json
+    assert_equal singer.to_json, @response.body
+  end
+end
+
+class ConsumeWithOptionsOverridingConfigurationTest < ConsumeTest
+  include Roar::Rails::TestCase
+  
+  class SingersController < ActionController::Base
+    include Roar::Rails::ControllerAdditions
+    respond_to :json
+    represents :json, :entity => Object
+
+    def consume_json
+      singer = consume!(Singer.new, :represent_with => SingerRepresenter)
+      render :text => singer.to_json
+    end
+  end
+
+  tests SingersController
+  
+  test "#consume uses #represents config to parse incoming document" do
+    post :consume_json, "{\"name\": \"Bumi\"}", :format => :json
+    assert_equal singer.to_json, @response.body
+  end
+end

data/test/responder_test.rb

@@ -11,112 +11,203 @@ module SingersRepresenter
   end
 end
 
+module ObjectRepresenter
+end
+module ObjectsRepresenter
+end
+
+class RepresentsTest < MiniTest::Spec
+  class SingersController
+  end
+  
+  before do
+    @controller = Class.new do
+      include Roar::Rails::ControllerAdditions
+    end.new
+  end
+  
+  describe "representer_for" do
+    describe "nothing configured" do
+      before do
+        @controller = class ::SingersController
+          include Roar::Rails::ControllerAdditions
+          self
+        end.new
+      end
+      
+      it "uses model class" do
+        assert_equal SingerRepresenter, @controller.representer_for(:json, Singer.new)
+      end
+      
+      it "uses plural controller name when collection" do
+        assert_equal SingersRepresenter, @controller.representer_for(:json, [])
+      end
+    end
+    
+    describe "represents :json, Singer" do
+      before do
+        @controller = class ::WhateverController < ActionController::Base
+          include Roar::Rails::ControllerAdditions
+          represents :json, Object
+          self
+        end.new
+      end
+      
+      it "uses defined class for item" do
+        assert_equal ObjectRepresenter, @controller.representer_for(:json, Singer.new)
+      end
+      
+      it "uses plural name when collection" do
+        assert_equal ObjectsRepresenter, @controller.representer_for(:json, [])
+      end
+    end
+    
+    
+    describe "represents :json, :entity => SingerRepresenter" do
+      before do
+        @controller = class ::FooController < ActionController::Base
+          include Roar::Rails::ControllerAdditions
+          represents :json, :entity => "ObjectRepresenter"
+          self
+        end.new
+      end
+      
+      it "returns :entity representer name" do
+        assert_equal "ObjectRepresenter", @controller.representer_for(:json, Singer.new)
+      end
+      
+      it "doesn't infer collection representer" do
+        assert_equal nil, @controller.representer_for(:json, [])
+      end
+    end
+    
+    describe "represents :json, :entity => SingerRepresenter, :collection => SingersRepresenter" do
+      before do
+        @controller = class ::BooController < ActionController::Base
+          include Roar::Rails::ControllerAdditions
+          represents :json, :entity => "ObjectRepresenter", :collection => "SingersRepresenter"
+          self
+        end.new
+      end
+      
+      it "uses defined class for item" do
+        assert_equal "ObjectRepresenter", @controller.representer_for(:json, Singer.new)
+      end
+      
+      it "uses defined class when collection" do
+        assert_equal "SingersRepresenter", @controller.representer_for(:json, [])
+      end
+    end
+  end
+end
+
 
 class ResponderTest < ActionController::TestCase
   include Roar::Rails::TestCase
   
-  class SingersController < ActionController::Base
+  class BaseController < ActionController::Base
     include Roar::Rails::ControllerAdditions
     respond_to :json
-
+    
     def execute
       instance_exec &@block
     end
   end
   
-  def get(&block)
-    @controller.instance_eval do
-      @block = block
+  class UnconfiguredControllerTest < ResponderTest
+    class SingersController < BaseController
     end
     
-    super :execute, :format => 'json'
-  end
-  
-  
-  tests SingersController
-  
-  test ":with_representer is deprecated" do
-    assert_deprecated do
+    tests SingersController
+    
+    test "responder finds SingerRepresenter representer by convention" do
       get do
-        singer = Musician.new("Bumi")
-        respond_with singer, :with_representer => SingerRepresenter
+        singer = Singer.new("Bumi")
+        respond_with singer
       end
+      
+      assert_equal singer.to_json, @response.body
+    end
+    
+    test "responder finds SingersRepresenter for collections by convention" do
+      get do
+        singers = [Singer.new("Bumi"), Singer.new("Bjork"), Singer.new("Sinead")]
+        respond_with singers
+      end
+      
+      assert_equal({:singers => singers.collect {|s| s.extend(SingerRepresenter).to_hash }}.to_json, @response.body)
     end
   end
   
-  
-  test "responder allows specifying representer" do # TODO: remove in 1.0.
-    get do
-      singer = Musician.new("Bumi")
-      respond_with singer, :with_representer => SingerRepresenter
+  class RespondToOptionsOverridingConfigurationTest < ResponderTest
+    class SingersController < BaseController
+      represents :json, Object
     end
     
-    assert_equal singer.to_json, @response.body
-  end
-
-  test "responder finds representer by convention" do
-    get do
-      singer = Singer.new("Bumi")
-      respond_with singer
+    tests SingersController
+    
+    test "responder uses passed representer" do
+      get do
+        singer = Singer.new("Bumi")
+        respond_with singer, :represent_with => SingerRepresenter
+      end
+      
+      assert_equal singer.to_json, @response.body
     end
     
-    assert_equal singer.to_json, @response.body
-  end
-  
-  
-
-  test "responder works with collections" do # TODO: remove in 1.0.
-    assert_deprecated do
+    test "responder uses passed representer for collection" do
       get do
         singers = [Singer.new("Bumi"), Singer.new("Bjork"), Singer.new("Sinead")]
-        respond_with singers
+        respond_with singers, :represent_with => SingersRepresenter
       end
+      
+      assert_equal({:singers => singers.collect {|s| s.extend(SingerRepresenter).to_hash }}.to_json, @response.body)
     end
     
-    assert_equal singers.map(&:to_hash).to_json, @response.body
-  end
-
-  test "custom responder works with collections" do  # TODO: remove in 1.0.
-    get do
-      singers = [Singer.new("Bumi"), Singer.new("Bjork"), Singer.new("Sinead")]
-      respond_with singers, :with_representer => SingerAliasRepresenter
+    test "responder uses passed representer for collection items when :represent_items_with set" do
+      get do
+        singers = [Singer.new("Bumi"), Singer.new("Bjork"), Singer.new("Sinead")]
+        respond_with singers, :represent_items_with => SingerRepresenter
+      end
+      
+      assert_equal(singers.collect {|s| s.extend(SingerRepresenter).to_hash }.to_json, @response.body)
     end
-    
-    assert_equal singers.map {|s| s.extend(SingerAliasRepresenter).to_hash }.to_json, @response.body
   end
   
-  
-  
-  test "use passed :represent_with representer for single model" do
-    get do
-      singer = Musician.new("Bumi")
-      respond_with singer, :with_representer => SingerRepresenter
+  class ConfiguredControllerTest < ResponderTest
+    class MusicianController < BaseController
+      represents :json, :entity => SingerRepresenter, :collection => SingersRepresenter
     end
     
-    assert_equal singer.extend(SingerRepresenter).to_json, @response.body
-  end
-  
-  test "use passed :represent_with representer for collection" do
-    get do
-      singers = [Singer.new("Bumi"), Singer.new("Bjork"), Singer.new("Sinead")]
-      respond_with singers, :represent_with => SingersRepresenter
+    tests MusicianController
+    
+    test "responder uses configured representer" do
+      get do
+        singer = Singer.new("Bumi")
+        respond_with singer
+      end
+      
+      assert_equal singer.to_json, @response.body
     end
     
-    assert_equal({:singers => singers.collect {|s| s.extend(SingerRepresenter).to_hash }}.to_json, @response.body)
+    test "responder uses configured representer for collection" do
+      get do
+        singers = [Singer.new("Bumi"), Singer.new("Bjork"), Singer.new("Sinead")]
+        respond_with singers
+      end
+      
+      assert_equal({:singers => singers.collect {|s| s.extend(SingerRepresenter).to_hash }}.to_json, @response.body)
+    end
   end
   
-  test "use passed :represent_items_with for collection items" do
-    get do
-      singers = [Singer.new("Bumi"), Singer.new("Bjork"), Singer.new("Sinead")]
-      respond_with singers, :represent_items_with => SingerRepresenter
+  def get(&block)
+    @controller.instance_eval do
+      @block = block
     end
     
-    assert_equal(singers.collect {|s| s.extend(SingerRepresenter).to_hash }.to_json, @response.body)
+    super :execute, :format => 'json'
   end
   
-  
-  
-
   def singer(name="Bumi")
     singer = Musician.new(name)
     singer.extend SingerRepresenter

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: roar-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-10 00:00:00.000000000 Z
+date: 2012-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roar