roar 0.9.1 → 0.9.2

data/CHANGES.markdown

@@ -1,3 +1,7 @@
+h2. 0.9.2
+
+* Using representable-1.1.
+
 h2. 0.9.1
 
 * Removed @Representer#to_attributes@ and @#from_attributes@.

data/README.textile

@@ -4,6 +4,7 @@ _Resource-Oriented Architectures in Ruby._
 
 "Lets make documents suit our models and not models fit to documents."
 
+Questions? Need help? Free 1st Level Support on irc.freenode.org#roar !
 
 h2. Introduction
 
@@ -61,13 +62,22 @@ Representers are the key ingredience in Roar, so let's check them out!
 
 h2. Representers
 
-To render a representational document, the backend service has to define a representer.
+Representers are most usable when defined in a module, and then mixed into a host class. In our example, the host class is the article.
+
+<pre>
+class Article
+  attr_accessor :title, :id
+end
+</pre>
+
+To render a representational document from the article, the backend service has to define a representer.
 
 <pre>
 require 'roar/representer/json'
 require 'roar/representer/feature/hypermedia'
 
-class Article
+
+module ArticleRepresenter
   include Roar::Representer::JSON
   include Roar::Representer::Feature::Hypermedia
   
@@ -75,22 +85,22 @@ class Article
   property :id
   
   link :self do
-    article_url(represented)
+    article_url(self)
   end 
 end
 </pre>
 
-Hooray, we can define plain properties and embedd links easily - and we can even use URL helpers (in Rails). There's even more, nesting, collections, but more on that later!
+Hooray, we can define plain properties and embedd links easily - and we can even use URL helpers (in Rails, using the "roar-rails gem":https://github.com/apotonick/roar-rails). There's even more, nesting, collections, but more on that later!
 
 
 h3. Rendering Representations in the Service
 
 In order to *render* an actual document, the backend service would have to do a few steps: creating a representer, filling in data, and then serialize it.
 
-<pre>Article.new(
-  title: "Lonestar",
-  id:    666).
-  to_json # => "{\"article\":{\"id\":666, ...
+<pre>loney = Article.new.extend(ArticleRepresenter)
+  loney.title = "Lonestar"
+  loney.id    = 666
+  loney.to_json # => "{\"article\":{\"id\":666, ...
 </pre>
 
 Articles itself are useless, so they may be placed into orders. This is the next example.
@@ -120,10 +130,18 @@ What if we wanted to check an existing order? We'd @GET http://orders/1@, right?
 }
 </pre>
 
+The order model is simple.
+
+<pre>
+class Order
+  attr_accessor :id, :client_id, :articles
+end
+</pre>
+
 Since orders may contain a composition of articles, how would the order service define its representer?
 
 <pre>
-class Order 
+module OrderRepresenter
   include Roar::Representer::JSON
   include Roar::Representer::Feature::Hypermedia
 
@@ -142,6 +160,8 @@ class Order
 end
 </pre>
 
+Representers don't have to be in modules, but can be 
+
 The declarative @#collection@ method lets us define compositions of representers.
 
 
@@ -153,12 +173,13 @@ If we were to implement an endpoint for creating new orders, we'd allow POST to
 
 <pre>
   post "/orders" do
-    incoming = Order.deserialize(request.body.string)
-    puts incoming.to_attributes #=> {:client_id => 815}
+    order = Order.new.extend(OrderRepresenter)
+    order.from_json(request.body.string)
+    order.to_json
   end
 </pre>
  
-Look how the @#to_attributes@ method helps extracting data from the incoming document and, again, @#to_json@ returns the freshly created order's representation. Roar's representers are truely working in both directions, rendering and parsing and thus prevent you from redundant knowledge sharing.
+Look how the @#from_json@ method helps extracting data from the incoming document and, again, @#to_json@ returns the freshly created order's representation. Roar's representers are truely working in both directions, rendering and parsing and thus prevent you from redundant knowledge sharing.
 
 
 h2. Representers in the Client

data/Rakefile

@@ -10,9 +10,3 @@ Rake::TestTask.new(:test) do |test|
   test.test_files = FileList['test/*_test.rb'] - ['test/integration_test.rb', 'test/active_record_integration_test.rb']
   test.verbose = true
 end
-
-Rake::TestTask.new(:testrails) do |test|
-  test.libs << 'test'
-  test.test_files = FileList['test/rails/*_test.rb']
-  test.verbose = true
-end

data/lib/roar/representer/feature/http_verbs.rb

@@ -27,7 +27,7 @@ module Roar
         # and updates properties accordingly.
         def post(url, format)
           # DISCUSS: what if a redirect happens here?
-          document = http.post_uri(url, serialize, format).body
+          document = http.post_uri(url, serialize(:links => false), format).body
           deserialize(document)
         end
         

data/lib/roar/version.rb

@@ -1,3 +1,3 @@
 module Roar
-  VERSION = "0.9.1"
+  VERSION = "0.9.2"
 end

data/roar.gemspec

@@ -19,9 +19,9 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
-  s.add_runtime_dependency "representable", "~> 1.0.1"
+  s.add_runtime_dependency "representable", "~> 1.1"
   
   s.add_development_dependency "test_xml"
-  s.add_development_dependency "minitest",         "~> 1.6.0"
-  s.add_development_dependency "sinatra",          "~> 1.2.6"
+  s.add_development_dependency "minitest",	">= 2.8.1"
+  s.add_development_dependency "sinatra",   "~> 1.2.6"
 end

data/test/Gemfile

@@ -1,7 +1,4 @@
 source "http://rubygems.org"
 
 gem "sinatra"
-gem "sinatra-contrib", :path => "./sinatra-contrib"
-gem "sinatra-activerecord"
 gem "roar", :path => ".."
-gem "representable", :path => "../../representable"

data/test/fake_server.rb

@@ -1,7 +1,5 @@
 require "bundler/setup"
 require 'sinatra/base'
-require 'sinatra/reloader'
-
 
 class FakeServer < Sinatra::Base
   get "/method" do

data/test/test_helper.rb

@@ -8,29 +8,6 @@ require 'roar/representer'
 require 'roar/representer/feature/hypermedia'
 require 'roar/representer/feature/http_verbs'
 
-# TODO: 2BRM.
-  module TestModel
-    def self.included(base)
-      base.extend ClassMethods
-    end
-    
-    
-    module ClassMethods
-      def accessors(*names)
-        names.each do |name|
-          attr_accessor name
-        end
-      end
-    end
-    
-    attr_accessor :attributes
-    
-    def initialize(attributes={})
-      attributes.each do |k,v|
-        send("#{k}=", v)
-      end
-    end
-  end
 
 module AttributesContructor
   def initialize(attrs={})
@@ -40,33 +17,19 @@ module AttributesContructor
   end
 end
 
-
-
 class Item
-  include TestModel
-  accessors :value
-  
-  def self.model_name
-    "item"
-  end
+  include AttributesContructor
+  attr_accessor :value
 end
 
 class Position
-  include TestModel
-  accessors :id, :item
-  
-  def self.model_name
-    :order
-  end
+  include AttributesContructor
+  attr_accessor :id, :item
 end
 
 class Order
-  include TestModel
-  accessors :id, :items
-  
-  def self.model_name
-    :order
-  end
+  include AttributesContructor
+  attr_accessor :id, :items
 end
 
 require "test_xml/mini_test"

data/test/xml_representer_test.rb

@@ -42,12 +42,8 @@ end
 
 class XMLRepresenterFunctionalTest < MiniTest::Spec
   class GreedyOrder
-    include TestModel
-    accessors :id, :items
-    
-    def self.model_name
-      :order
-    end
+    include AttributesContructor
+    attr_accessor :id, :items
   end
   
   class TestXmlRepresenter

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 9
-  - 1
-  version: 0.9.1
+  - 2
+  version: 0.9.2
 platform: ruby
 authors: 
 - Nick Sutterer
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-28 00:00:00 +01:00
+date: 2012-02-06 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -27,9 +27,8 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 1
-        - 0
         - 1
-        version: 1.0.1
+        version: "1.1"
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -51,13 +50,13 @@ dependencies:
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version 
         segments: 
+        - 2
+        - 8
         - 1
-        - 6
-        - 0
-        version: 1.6.0
+        version: 2.8.1
   type: :development
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
@@ -93,9 +92,6 @@ files:
 - TODO.markdown
 - lib/roar.rb
 - lib/roar/rails.rb
-- lib/roar/rails/controller_methods.rb
-- lib/roar/rails/representer_methods.rb
-- lib/roar/rails/test_case.rb
 - lib/roar/representer.rb
 - lib/roar/representer/feature/http_verbs.rb
 - lib/roar/representer/feature/hypermedia.rb

data/lib/roar/rails/controller_methods.rb

@@ -1,71 +0,0 @@
-require 'active_support/core_ext/class/attribute'
-
-module Roar
-  module Rails
-    module ControllerMethods
-      extend ActiveSupport::Concern
-      
-      included do |base|
-        base.responder = Responder
-        base.class_attribute :represented_class
-      end
-      
-      module ClassMethods
-        # Sets the represented class for the controller.
-        def represents(model_class)
-          self.represented_class = model_class
-        end
-      end
-      
-    #private
-      def representer_class_for(model_class, format)
-        # DISCUSS: upcase and static namespace is not cool, but works for now.
-        "Representer::#{format.to_s.upcase}::#{model_class}".constantize
-      end
-      
-      # Returns a representer instance that has parsed the request body.
-      def incoming
-        representer = representer_class_for(self.class.represented_class, formats.first).deserialize(request.raw_post)
-      end
-      
-      
-      # Returns the deserialized representation as a hash suitable for #create and #update_attributes.
-      def representation
-        incoming.to_nested_attributes
-      end
-      
-      
-      class Responder < ActionController::Responder
-        def display(resource, given_options={})
-          # TODO: find the correct representer for #format.
-          # TODO: should we infer the represented class per default?
-          # TODO: unit-test this method.
-          #representer = controller.representer_class_for(resource.class, format)
-          representer = controller.representer_class_for(controller.represented_class, format)
-          
-          # DISCUSS: do that here?
-          #representer.extend(RepresenterMethods::ClassMethods)
-          
-          controller.render given_options.merge!(options).merge!(
-            format => representer.serialize_model_with_controller(resource, controller)
-          )
-        end
-        
-        # This is the common behavior for formats associated with APIs, such as :xml and :json.
-        def api_behavior(error)
-          if has_errors?
-            controller.render :text => resource.errors, :status => :unprocessable_entity # TODO: which media format? use an ErrorRepresenter shipped with Roar.
-          elsif get?
-            display resource
-          elsif post?
-            display resource, :status => :created, :location => api_location
-          elsif put?
-            display resource
-          else
-            head :ok
-          end
-        end
-      end
-    end
-  end
-end

data/lib/roar/rails/representer_methods.rb

@@ -1,53 +0,0 @@
-module Roar
-  module Rails
-    # Makes Rails URL helpers work in representers. Dependent on Rails.application.
-    module RepresenterMethods
-      extend ActiveSupport::Concern
-      
-      included do |base|
-        base.class_eval do
-          attr_accessor :_controller
-          delegate :request, :env, :to => :_controller
-          
-          include ActionController::UrlFor
-          include ::Rails.application.routes.url_helpers
-          
-          extend Conventions
-        end
-      end
-      
-      module ClassMethods
-        # TODO: test?
-        def for_model_with_controller(represented, controller)
-          # DISCUSS: use #for_model_attributes for overriding?
-          from_attributes(compute_attributes_for(represented)) do |rep| 
-            rep.represented = represented
-            rep._controller = controller 
-          end
-        end
-        
-        # TODO: test?
-        def serialize_model_with_controller(represented, controller)
-          for_model_with_controller(represented, controller).serialize
-        end
-      end
-      
-      # Introduces strongly opinionated convenience methods in Representer.
-      module Conventions
-        def representation_name
-          super.to_s.singularize
-        end
-        
-        def collection(name, options={})
-          namespace     = self.name.split("::")[-2] # FIXME: this assumption is pretty opinionated.
-          singular_name = name.to_s.singularize
-          
-          super name, options.reverse_merge(
-            :class => "representer/#{namespace}/#{singular_name}".classify.constantize,
-            #:tag => singular_name  # FIXME: how/where to decide if singular TAG or not?
-            )
-        end
-      end
-    end
-  end
-end

data/lib/roar/rails/test_case.rb

@@ -1,69 +0,0 @@
-#require 'test_xml/test_unit'
-require 'action_controller/test_case'
-
-module Roar::Rails
-  module TestCase
-    def process(action, *args)
-      raise
-      if args.first.is_a?(String)
-        puts "YO"
-         request.env['RAW_POST_DATA'] = args.shift
-         method = args.pop
-         args << nil
-         args << method
-      end
-    
-      super
-    end
-    
-    def assert_response(status, headers={})  # FIXME: allow message.
-      super
-      
-      if headers.is_a?(Hash)
-        assert_headers(headers)
-      else
-        assert_body(headers)
-      end
-    end
-    
-    def assert_headers(headers)
-      headers.each_pair do |k,v|
-        assert_equal v, @response.headers[k]
-      end
-    end
-    
-    def assert_body(body, options={})
-      return assert_xml_equal body, @response.body if options[:format] == :xml  # FIXME: how do we know whether assert_xml is appropriate?
-      assert_equal body, @response.body
-    end
-  end
-end
-
-
-ActionController::TestCase::Behavior.class_eval do
-  # FIXME: ugly monkey-patching.
-  # TODO: test:
-  #   put :create
-  #   put :create, :format => :xml
-  #   put :create, "<order/>", :format => :xml
-  #   put :create, "<order/>"
-  
-  
-  include Roar::Rails::TestCase
-end
-
-RSpec::Rails::ControllerExampleGroup.class_eval do
-  #include Roar::Rails::TestCase
-  # FIXME: include module!
-  
-  def process(action, *args)
-    if args.first.is_a?(String)
-       request.env['RAW_POST_DATA'] = args.shift
-       method = args.pop
-       args << nil
-       args << method
-    end
-  
-    super
-  end
-end