acts_as_api 0.3.2 → 0.3.3

data/History.txt

@@ -1,4 +1,18 @@
-=== 0.3.0 TO BE RELEASED AS A GEM
+=== 0.3.3 2011-04-24
+
+* Added support for :if and :unless options
+
+=== 0.3.2 2011-04-20
+
+* Raise an exception if a specified api template is not found 
+
+=== 0.3.1 2011-04-08
+
+* Added the :template option to specify sub templates
+
+* Fixed a bug concerning extended api templates 
+
+=== 0.3.0 2011-02-22
 
 * Added bundler support
 

data/README.rdoc

@@ -35,6 +35,9 @@ A nice introduction about acts_as_api with examples can be found here:
 
 http://fabrik42.github.com/acts_as_api
 
+See the Wiki for a lot of usage examples and features:
+
+https://github.com/fabrik42/acts_as_api/wiki
 
 == Features:
 

data/lib/acts_as_api/api_template.rb

@@ -1,27 +1,133 @@
 module ActsAsApi
-  #
+  # Represents an api template for a model.
+  # This class should not be initiated by yourself, api templates
+  # are created by defining them in the model by calling: +api_accessible+.
+  # 
+  # The api template is configured in the block passed to +api_accessible+.
+  # 
+  # Please note that +ApiTemplate+ inherits from +Hash+ so you can use all
+  # kind of +Hash+ and +Enumerable+ methods to manipulate the template.
   class ApiTemplate < Hash
 
-    def options_for(key)
-      @options[key]
-    end
-    
-    def option_for(key, value)
-      @options[key][value] if @options[key]
+    # The name of the api template as a Symbol.
+    attr_accessor :api_template
+
+    # Returns a new ApiTemplate with the api template name
+    # set to the passed template.
+    def self.create(template)
+      t = ApiTemplate.new
+      t.api_template = template
+      return t
     end
 
+    # Adds an item to the api template
+    #
+    # The value passed can be one of the following:
+    #  * Symbol - the method with the same name will be called on the model when rendering.
+    #  * String - must be in the form "method1.method2.method3", will call this method chain.
+    #  * Hash - will be added as a sub hash and all its items will be resolved the way described above.
+    #
+    # Possible options to pass:
+    #  * :template - Determine the template that should be used to render the item if it is
+    #    +api_accessible+ itself.
     def add(val, options = {})
       item_key = (options[:as] || val).to_sym
-      
+
       self[item_key] = val
-      
+
       @options ||= {}
       @options[item_key] = options
     end
 
-    def remove(key)
-      self.delete(key)
+    # Removes an item from the template
+    def remove(item)
+      self.delete(item)
+    end
+
+    # Returns the options of an item in the api template
+    def options_for(item)
+      @options[item]
     end
 
+    # Returns the passed option of an item in the api template
+    def option_for(item, option)
+      @options[item][option] if @options[item]
+    end
+    
+    # If a special template name for the passed item is specified
+    # it will be returned, if not the original api template.
+    def api_template_for(parent, item)
+      return api_template unless parent.is_a? ActsAsApi::ApiTemplate
+      parent.option_for(item, :template) || api_template
+    end
+    
+    # Decides if the passed item should be added to
+    # the response.
+    def allowed_to_render?(parent, item, model)
+      return true unless parent.is_a? ActsAsApi::ApiTemplate
+      allowed = true
+      allowed = condition_fulfilled?(model, parent.option_for(item, :if)) if parent.option_for(item, :if)
+      allowed = !(condition_fulfilled?(model, parent.option_for(item, :unless))) if parent.option_for(item, :unless)
+      return allowed
+    end
+    
+    def condition_fulfilled?(model, condition)
+      case condition
+      when Symbol
+        result = model.send(condition)
+      when Proc
+        result = condition.call(model)
+      end
+      !result.nil? && !result.is_a?(FalseClass)
+    end
+
+    # Generates a hash that represents the api response based on this
+    # template for the passed model instance.
+    def to_response_hash(model)
+      queue = []
+      api_output = {}
+      queue << { :parent =>  api_output, :item => self }
+
+      until queue.empty? do
+          leaf = queue.pop
+
+          leaf[:item].each do |k,v|
+
+            next unless allowed_to_render?(leaf[:item], k, model)
+
+            case v
+            when Symbol
+              if model.respond_to?(v)
+                out = model.send v
+              end
+
+            when Proc
+              out = v.call(model)
+
+            when String
+              # go up the call chain
+              out = model
+              v.split(".").each do |method|
+                out = out.send(method.to_sym)
+              end
+
+            when Hash
+              leaf[:parent][k] ||= {}
+              queue << { :parent =>  leaf[:parent][k], :item => v}
+              next
+            end
+
+            if out.respond_to?(:as_api_response)
+              sub_template = api_template_for(leaf[:item], k)
+              out = out.send(:as_api_response, sub_template)
+            end
+
+            leaf[:parent][k] = out
+          end
+        end
+
+        api_output
+      end
+
+    end
   end
-end

data/lib/acts_as_api/array.rb

@@ -1,4 +1,4 @@
-# The standard ruby Array class is extended by one method.
+# The standard ruby Array class is extended by one instance method.
 class Array
 
   # Neccessary to render an Array of models, e.g. the result of a search.

data/lib/acts_as_api/base.rb

@@ -32,15 +32,9 @@ module ActsAsApi
       # *Note*: There is only whitelisting for api accessible attributes.
       # So once the model acts as api, you have to determine all attributes here that should
       # be contained in the api responses.
-      def api_accessible_deprecated(api_templates)
-        api_templates.each do |api_template, attributes|
-          write_inheritable_attribute("api_accessible_#{api_template}".to_sym, Set.new(attributes) + (api_accessible_attributes(api_template) || []))
-        end
-      end
-
       def api_accessible(api_template, options = {}, &block)
 
-        attributes = api_accessible_attributes(api_template) || ApiTemplate.new
+        attributes = api_accessible_attributes(api_template) || ApiTemplate.create(api_template)
 
         attributes.merge!(api_accessible_attributes(options[:extend])) if options[:extend]
 
@@ -55,75 +49,22 @@ module ActsAsApi
       def api_accessible_attributes(api_template)
         read_inheritable_attribute("api_accessible_#{api_template}".to_sym)
       end
-
     end
 
     module InstanceMethods
 
       # Creates the api response of the model and returns it as a Hash.
+      # Will raise an exception if the passed api template is not defined for the model
       def as_api_response(api_template)
         api_attributes = self.class.api_accessible_attributes(api_template)
-
+        
         raise "acts_as_api template :#{api_template.to_s} was not found for model #{self.class}" if api_attributes.nil?
-
-        api_output = {}
-
-        return api_output if api_attributes.nil?
-
-        queue = []
-        queue << { :parent =>  api_output, :item => api_attributes}
-
-        until queue.empty? do
-
-            leaf = queue.pop
-
-            leaf[:item].each do |k,v|
-
-              if leaf[:item].respond_to?(:option_for)
-                sub_template = leaf[:item].option_for(k, :template) || api_template
-              else
-                sub_template = api_template
-              end
-
-              case v
-              when Symbol
-
-                if self.respond_to?(v)
-                  out = send v
-                end
-
-              when Proc                
-                out = v.call(self)
-
-              when String
-                # go up the call chain
-                out = self
-                v.split(".").each do |method|
-                  out = out.send(method.to_sym)
-                end
-
-              when Hash
-                leaf[:parent][k] ||= {}
-                queue << { :parent =>  leaf[:parent][k], :item => v}
-                next
-              end
-              
-              if out.respond_to?(:as_api_response)
-                out = out.send(:as_api_response, sub_template)              
-              end
-              
-              leaf[:parent][k] = out
-
-            end
-
-          end
-
-          api_output
-
-        end
-
+        
+        api_attributes.to_response_hash(self)
       end
 
     end
-    
+
   end
+
+end

data/lib/acts_as_api/config.rb

@@ -23,8 +23,12 @@ module ActsAsApi
       # automatically      
       attr_accessor_with_default :default_root, :record
       
+      # If true a json response will be automatically wrapped into
+      # a JavaScript function call in case a :callback param is passed.
       attr_accessor_with_default :allow_jsonp_callback, false
       
+      # If true the jsonp function call will get the http status passed
+      # as a second parameter
       attr_accessor_with_default :add_http_status_to_jsonp_response, true      
 
     end

data/lib/acts_as_api/rails_renderer.rb

@@ -1,5 +1,7 @@
 module ActsAsApi
-  # Contains rails specific renderers used by acts_as_api
+  # Contains rails specific renderers used by acts_as_api to render a jsonp response
+  #
+  # See ActsAsApi::Config about the possible configurations
   module RailsRenderer
 
     def self.setup

data/lib/acts_as_api/version.rb

@@ -1,4 +1,3 @@
 module ActsAsApi
-  
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

data/lib/acts_as_api.rb

@@ -1,12 +1,11 @@
-require 'set'
 require 'active_model'
 require 'active_support/core_ext/class'
 
 $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
   
- require "acts_as_api/array"
- require "acts_as_api/rails_renderer"
+require "acts_as_api/array"
+require "acts_as_api/rails_renderer"
 
 # acts_as_api is a gem that aims to make the construction of JSON and XML
 # responses in rails 3 easy and fun.

data/spec/controllers/users_controller_spec.rb

@@ -67,7 +67,7 @@ describe UsersController, :orm => :active_record do
         get :index, :format => 'json', :api_template => :name_only
       end
 
-      it "should have a root node named users" do
+      it "should have a root node named users" do        
         response_body_json.should have_key("users")
       end
 
@@ -93,7 +93,7 @@ describe UsersController, :orm => :active_record do
         get :show, :format => 'json', :api_template => :name_only, :id => @luke.id
       end
 
-      it "should have a root node named user" do
+      it "should have a root node named user" do        
         response_body_json.should have_key("user")
       end
 
@@ -163,7 +163,7 @@ describe UsersController, :orm => :active_record do
           get :index, :format => 'json', :api_template => :name_only, :callback => @callback
         end
 
-        it "should wrap the response in the callback" do
+        it "should wrap the response in the callback" do        
           response_body_jsonp(@callback).should_not be_nil
         end
 
@@ -175,7 +175,7 @@ describe UsersController, :orm => :active_record do
           get :show, :format => 'json', :api_template => :name_only, :id => @luke.id, :callback => @callback
         end
 
-        it "should wrap the response in the callback" do
+        it "should wrap the response in the callback" do          
           response_body_jsonp(@callback).should_not be_nil
         end
 
@@ -184,5 +184,4 @@ describe UsersController, :orm => :active_record do
     end
   end
 
-
 end

data/spec/models/base/associations_spec.rb

@@ -0,0 +1,284 @@
+require File.dirname(__FILE__) + '/../../spec_helper.rb'
+
+describe ActsAsApi::Base do
+
+  describe "including an association in the api template", :orm => :active_record do
+
+    before(:each) do
+      setup_models
+    end
+
+    after(:each) do
+      clean_up
+    end
+
+    describe "which doesn't acts_as_api" do
+
+      before(:each) do
+        @response = @luke.as_api_response(:include_tasks)
+      end
+
+      it "returns a hash" do
+        @response.should be_kind_of(Hash)
+      end
+
+      it "returns the correct number of fields" do
+        @response.should have(1).key
+      end
+
+      it "returns all specified fields" do
+        @response.keys.should include(:tasks)
+      end
+
+      it "returns the correct values for the specified fields" do
+        @response[:tasks].should be_an Array
+        @response[:tasks].should have(3).tasks
+      end
+
+      it "should contain the associated sub models" do
+        @response[:tasks].should include(@destroy_deathstar, @study_with_yoda, @win_rebellion)
+      end
+    end
+
+    describe "which does acts_as_api" do
+
+      context "has_many" do
+
+        before(:each) do
+          Task.acts_as_api
+          Task.api_accessible :include_tasks do |t|
+            t.add :heading
+            t.add :done
+          end
+          @response = @luke.as_api_response(:include_tasks)
+        end
+
+        it "returns a hash" do
+          @response.should be_kind_of(Hash)
+        end
+
+        it "returns the correct number of fields" do
+          @response.should have(1).key
+        end
+
+        it "returns all specified fields" do
+          @response.keys.should include(:tasks)
+        end
+
+        it "returns the correct values for the specified fields" do
+          @response[:tasks].should be_an Array
+          @response[:tasks].should have(3).tasks
+        end
+
+        it "contains the associated child models with the determined api template" do
+          @response[:tasks].each do |task|
+            task.keys.should include(:heading, :done)
+            task.keys.should have(2).attributes
+          end
+        end
+
+        it "contains the correct data of the child models" do
+          task_hash = [  @destroy_deathstar, @study_with_yoda, @win_rebellion  ].collect{|t| { :done => t.done, :heading => t.heading } }
+          @response[:tasks].should eql task_hash
+        end
+      end
+
+      context "has_one" do
+
+        before(:each) do
+          Profile.acts_as_api
+          Profile.api_accessible :include_profile do |t|
+            t.add :avatar
+            t.add :homepage
+          end
+          @response = @luke.as_api_response(:include_profile)
+        end
+
+        it "returns a hash" do
+          @response.should be_kind_of(Hash)
+        end
+
+        it "returns the correct number of fields" do
+          @response.should have(1).key
+        end
+
+        it "returns all specified fields" do
+          @response.keys.should include(:profile)
+        end
+
+        it "returns the correct values for the specified fields" do
+          @response[:profile].should be_a Hash
+          @response[:profile].should have(2).attributes
+        end
+
+        it "contains the associated child models with the determined api template" do
+          @response[:profile].keys.should include(:avatar, :homepage)
+        end
+
+        it "contains the correct data of the child models" do
+          profile_hash = { :avatar => @luke.profile.avatar, :homepage => @luke.profile.homepage }
+          @response[:profile].should eql profile_hash
+        end
+
+      end
+    end
+
+    describe "which does acts_as_api, but with using another template name" do
+
+      before(:each) do
+        Task.acts_as_api
+        Task.api_accessible :other_template do |t|
+          t.add :description
+          t.add :time_spent
+        end
+        @response = @luke.as_api_response(:other_sub_template)
+      end
+
+      it "returns a hash" do
+        @response.should be_kind_of(Hash)
+      end
+
+      it "returns the correct number of fields" do
+        @response.should have(2).keys
+      end
+
+      it "returns all specified fields" do
+        @response.keys.should include(:first_name)
+      end
+
+      it "returns the correct values for the specified fields" do
+        @response.values.should include(@luke.first_name)
+      end
+
+      it "returns all specified fields" do
+        @response.keys.should include(:tasks)
+      end
+
+      it "returns the correct values for the specified fields" do
+        @response[:tasks].should be_an Array
+        @response[:tasks].should have(3).tasks
+      end
+
+      it "contains the associated child models with the determined api template" do
+        @response[:tasks].each do |task|
+          task.keys.should include(:description, :time_spent)
+          task.keys.should have(2).attributes
+        end
+      end
+
+      it "contains the correct data of the child models" do
+        task_hash = [  @destroy_deathstar, @study_with_yoda, @win_rebellion  ].collect{|t| { :description => t.description, :time_spent => t.time_spent } }
+        @response[:tasks].should eql task_hash
+      end
+    end
+
+    describe "that is scoped" do
+
+      before(:each) do
+        # extend task model with scope
+        class Task < ActiveRecord::Base
+          scope :completed, where(:done => true)
+        end
+        Task.acts_as_api
+        Task.api_accessible :include_completed_tasks do |t|
+          t.add :heading
+          t.add :done
+        end
+
+        @response = @luke.as_api_response(:include_completed_tasks)
+      end
+
+      it "returns a hash" do
+        @response.should be_kind_of(Hash)
+      end
+
+      it "returns the correct number of fields" do
+        @response.should have(1).key
+      end
+
+      it "returns all specified fields" do
+        @response.keys.should include(:completed_tasks)
+      end
+
+      it "returns the correct values for the specified fields" do
+        @response[:completed_tasks].should be_an Array
+        @response[:completed_tasks].should have(2).tasks
+      end
+
+      it "contains the associated child models with the determined api template" do
+        @response[:completed_tasks].each do |task|
+          task.keys.should include(:heading, :done)
+          task.keys.should have(2).attributes
+        end
+      end
+
+      it "contains the correct data of the child models" do
+        task_hash = [  @destroy_deathstar, @study_with_yoda  ].collect{|t| { :done => t.done, :heading => t.heading } }
+        @response[:completed_tasks].should eql task_hash
+      end
+    end
+
+    describe "handling nil values" do
+
+      context "has_many" do
+
+        before(:each) do
+          Task.acts_as_api
+          Task.api_accessible :include_tasks do |t|
+            t.add :heading
+            t.add :done
+          end
+          @response = @han.as_api_response(:include_tasks)
+        end
+
+        it "returns a hash" do
+          @response.should be_kind_of(Hash)
+        end
+
+        it "returns the correct number of fields" do
+          @response.should have(1).key
+        end
+
+        it "returns all specified fields" do
+          @response.keys.should include(:tasks)
+        end
+
+        it "returns the correct values for the specified fields" do
+          @response[:tasks].should be_kind_of(Array)
+        end
+
+        it "contains no associated child models" do
+          @response[:tasks].should have(0).items
+        end
+
+      end
+
+      context "has one" do
+        before(:each) do
+          Profile.acts_as_api
+          Profile.api_accessible :include_profile do |t|
+            t.add :avatar
+            t.add :homepage
+          end
+          @response = @han.as_api_response(:include_profile)
+        end
+
+        it "returns a hash" do
+          @response.should be_kind_of(Hash)
+        end
+
+        it "returns the correct number of fields" do
+          @response.should have(1).key
+        end
+
+        it "returns all specified fields" do
+          @response.keys.should include(:profile)
+        end
+
+        it "returns nil for the association" do
+          @response[:profile].should be_nil
+        end
+      end
+    end
+  end
+end