brainstem 0.2.4 → 0.2.5

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NDQ4OWNhYzY3M2FjZDI3NTAwMGY3MjhmNTc4NTFmZTY5NmU0MDc4YQ==
+  data.tar.gz: !binary |-
+    MjNhMGMzZjdlYTE0MzZkZjJmNzNhN2VkZDUwYzJmOWMyMGI4ZDRkZQ==
+SHA512:
+  metadata.gz: !binary |-
+    ZmI4MDIwN2JjODg0YWMxYzFjODBjYWY4ZDdmMDgzNzM4YWFjNGQyY2Q4NTg4
+    ZGI2NDljNzdkNjBkYzNmNjkzZWUyNjIzZjBiNjc4OWUxMGUzZDFhYjY3Yzhj
+    MzM2YTA5ZmY1OTM1MmU0MGU5NDM0ZTk4OGU1NDdhY2RlZTE4Mjg=
+  data.tar.gz: !binary |-
+    OWExMGE5Nzk5ODk2NzBjMjJhNzhjZWM4NTRiNjE4MWY5NDk0MDExNTNiZTk4
+    ZmYzNzkwNzE0Mzc1MTIzYmQ1Y2ZhYjYzOTU1MGQ0MjI3N2YwMTNjODFlNGFm
+    OTI5NDkwMjQzNDQwNDI1N2JiMWFjNGFmZjMxZGI3YjAzMGVlZGU=

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
++ **0.2.5** - _07/22/2014_
+
+  + `Brainstem::Presenter#load_associations!` now:
+    + polymorphic 'belongs_to' association is represented as a hash which includes:
+      + id: The id of the polymorphic object
+      + key: The table name for the class of the polymorphic object
+
 + **0.2.4** - _01/9/2014_
 
   + `Brainstem::ControllerMethods#present_object` now simulates an only request (by providing the `only` parameter to Brainstem) when attempting to present a single model.

data/Gemfile.lock

@@ -1,42 +1,51 @@
 PATH
   remote: .
   specs:
-    brainstem (0.2.4)
-      activerecord (>= 3.0)
+    brainstem (0.2.5)
+      activerecord (>= 3.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (3.2.13)
-      activesupport (= 3.2.13)
-      builder (~> 3.0.0)
-    activerecord (3.2.13)
-      activemodel (= 3.2.13)
-      activesupport (= 3.2.13)
-      arel (~> 3.0.2)
-      tzinfo (~> 0.3.29)
-    activesupport (3.2.13)
-      i18n (= 0.6.1)
-      multi_json (~> 1.0)
-    arel (3.0.2)
-    builder (3.0.4)
-    diff-lcs (1.2.2)
-    i18n (0.6.1)
-    multi_json (1.7.2)
-    rake (10.0.4)
-    redcarpet (2.2.2)
-    rr (1.0.5)
-    rspec (2.13.0)
-      rspec-core (~> 2.13.0)
-      rspec-expectations (~> 2.13.0)
-      rspec-mocks (~> 2.13.0)
-    rspec-core (2.13.1)
-    rspec-expectations (2.13.0)
-      diff-lcs (>= 1.1.3, < 2.0)
-    rspec-mocks (2.13.1)
-    sqlite3 (1.3.7)
-    tzinfo (0.3.37)
-    yard (0.8.5.2)
+    activemodel (4.1.6)
+      activesupport (= 4.1.6)
+      builder (~> 3.1)
+    activerecord (4.1.6)
+      activemodel (= 4.1.6)
+      activesupport (= 4.1.6)
+      arel (~> 5.0.0)
+    activesupport (4.1.6)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    arel (5.0.1.20140414130214)
+    builder (3.2.2)
+    diff-lcs (1.2.5)
+    i18n (0.6.11)
+    json (1.8.1)
+    minitest (5.4.2)
+    rake (10.3.2)
+    redcarpet (3.1.2)
+    rr (1.1.2)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.6)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+    sqlite3 (1.3.9)
+    thread_safe (0.3.4)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    yard (0.8.7.4)
 
 PLATFORMS
   ruby

data/README.md

@@ -26,68 +26,75 @@ Add this line to your application's Gemfile:
 
 Create a class that inherits from Brainstem::Presenter, named after the model that you want to present, and preferrably versioned in a module. For example:
 
-    module Api
-	  module V1
-	    class WidgetPresenter < Brainstem::Presenter
-	      presents "Widget"
-	
-	      # Available sort orders to expose through the API
-	      sort_order :updated_at, "widgets.updated_at"
-	      sort_order :created_at, "widgets.created_at"
-	
-	      # Default sort order to apply
-	      default_sort_order "updated_at:desc"
-	
-	      # Optional filter that delegates to the Widget model :popular scope, 
-	      # which should take one argument of true or false.
-	      filter :popular
-	
-	      # Optional filter that applies a lambda.
-	      filter :location_name do |scope, location_name|
-	        scope.joins(:locations).where("locations.name = ?", location_name)
-	      end
-	
-	      # Filter with an overridable default that runs on all requests.
-	      filter :include_legacy_widgets, :default => false do |scope, bool|
-	        bool ? scope : scope.without_legacy_widgets
-	      end
-	
-	      # Return a ruby hash that can be converted to JSON
-	      def present(widget)
-	        {
-	            :name           => widget.name,
-	            :legacy         => widget.legacy?,
-	            :updated_at     => widget.updated_at,
-	            :created_at     => widget.created_at,
-	            # Associations can be included by request
-	            :features       => association(:features),
-	            :location       => association(:location)
-	        }
-	      end
-	    end
-	  end
-	end
-
-Once you've created a presenter like the one above, pass requests through from your controller.
+```ruby
+module Api
+  module V1
+    class WidgetPresenter < Brainstem::Presenter
+      presents "Widget"
+
+      # Available sort orders to expose through the API
+      sort_order :updated_at, "widgets.updated_at"
+      sort_order :created_at, "widgets.created_at"
+
+      # Default sort order to apply
+      default_sort_order "updated_at:desc"
+
+      # Optional filter that delegates to the Widget model :popular scope,
+      # which should take one argument of true or false.
+      filter :popular
+
+      # Optional filter that applies a lambda.
+      filter :location_name do |scope, location_name|
+        scope.joins(:locations).where("locations.name = ?", location_name)
+      end
 
-    class Api::WidgetsController < ActionController::Base
-      include Brainstem::ControllerMethods
+      # Filter with an overridable default that runs on all requests.
+      filter :include_legacy_widgets, :default => false do |scope, bool|
+        bool ? scope : scope.without_legacy_widgets
+      end
 
-      def index
-        render :json => present("widgets") { Widgets.visible_to(current_user) }
+      # Return a ruby hash that can be converted to JSON
+      def present(widget)
+        {
+            :name           => widget.name,
+            :legacy         => widget.legacy?,
+            :updated_at     => widget.updated_at,
+            :created_at     => widget.created_at,
+            # Associations can be included by request
+            :features       => association(:features),
+            :location       => association(:location)
+        }
       end
     end
+  end
+end
+```
+
+Once you've created a presenter like the one above, pass requests through from your controller.
+
+```ruby
+class Api::WidgetsController < ActionController::Base
+  include Brainstem::ControllerMethods
+
+  def index
+    render :json => present("widgets") { Widgets.visible_to(current_user) }
+  end
+end
+```
 
 The scope passed to `present` could contain any starting conditions that you'd like.  Requests can have includes, filters, and sort orders.
 
-    GET /api/widgets.json?include=features&sort_order=popularity:desc&location_name=san+francisco
+    GET /api/widgets.json?include=features&order=popularity:desc&location_name=san+francisco
+
+Additionally, requests can have a 'pretty' parameter. When set to true, responses will be pretty-printed.
+Do this by adding `&pretty=true` to the above example.
 
 Responses will look like the following:
 
     {
       # Total number of results that matched the query.
       count: 5,
-      
+
       # A lookup table to top-level keys.  Necessary
       # because some objects can have associations of
       # the same type as themselves.
@@ -95,7 +102,7 @@ Responses will look like the following:
         { key: "widgets", id: "2" },
         { key: "widgets", id: "10" }
       ],
-      
+
       # Serialized models with any requested associations, keyed by ID.
 
       widgets: {
@@ -106,7 +113,7 @@ Responses will look like the following:
           popularity: 85,
           location_id: "2"
         },
-        
+
         "2": {
        	  id: "2",
        	  name: "flubber",
@@ -125,26 +132,42 @@ Responses will look like the following:
 
 You may want to setup an initializer in `config/initializers/brainstem.rb` like the following:
 
-    Brainstem.default_namespace = :v1
- 
-    module Api
-	  module V1
-	    module Helper
-	      def current_user
-	        # However you get your current user.
-	      end
-	    end
-	  end
-	end
-	Brainstem::Presenter.helper(Api::V1::Helper)
-	
-	require 'api/v1/widget_presenter'
-	require 'api/v1/feature_presenter'
-	require 'api/v1/location_presenter'
-	# ...
-	
-	# Or you could do something like this:
-	#  Dir[Rails.root.join("lib/api/v1/*_presenter.rb").to_s].each { |p| require p }
+```ruby
+Brainstem.default_namespace = :v1
+
+module Api
+  module V1
+    module Helper
+      def current_user
+        # However you get your current user.
+      end
+    end
+  end
+end
+Brainstem::Presenter.helper(Api::V1::Helper)
+
+require 'api/v1/widget_presenter'
+require 'api/v1/feature_presenter'
+require 'api/v1/location_presenter'
+# ...
+
+# Or you could do something like this:
+#  Dir[Rails.root.join("lib/api/v1/*_presenter.rb").to_s].each { |p| require p }
+```
+
+### A note on Rails 4 Style Scopes
+
+In Rails 3 it was acceptable to write scopes like this: `scope :popular, where(:popular => true)`. This was deprecated in Rails 4 in preference of scopes that include a callable object: `scope :popular, lambda { where(:popular) => true }`.
+
+If your scope does not take any parameters, this can cause a problem with Brainstem if you use a filter that delegates to that scope in your presenter. (e.g., `filter :popular`). The preferable way to handle this is to write a Brainstem scope that delegates to your model scope:
+
+```ruby
+filter :popular do |scope|
+    scope.popular
+ end
+```
+
+--
 
 For more detailed examples, please see the documentation for methods on {Brainstem::Presenter} and our detailed [Rails example application](https://github.com/mavenlink/brainstem-demo-rails).
 
@@ -158,16 +181,56 @@ APIs presented with Brainstem are just JSON APIs, so they can be consumed with j
       results: [
         { key: "widgets", id: "2" }, { key: "widgets", id: "10" }
       ],
-      
+
       widgets: {
         "10": {
           id: "10",
           name: "disco ball",
           …
 
-
 Brainstem returns objects as top-level hashes and provides a `results` array of `key` and `id` objects for finding the returned data in those hashes.  The reason that we use the `results` array is two-fold: 1st) it provides order outside of the serialized objects so that we can provide objects keyed by ID, and 2nd) it allows for polymorphic responses and for objects that have associations of their own type (like posts and replies or tasks and sub-tasks).
 
+### Test helpers
+
+Brainstem includes some spec helpers for controller specs. In order to use them, you need to include Brainstem in your controller specs by adding the following to `spec/support/brainstem.rb` or in your `spec/spec_helper.rb`:
+
+```ruby
+require 'brainstem/test_helpers'
+
+RSpec.configure do |config|
+  config.include Brainstem::TestHelpers, type: :controller
+end
+```
+
+Now you are ready to use the `brainstem_data` method.
+
+```ruby
+# Assume user is the model and name is an attribute
+
+# Selecting an item from a collection by it's id
+expect(brainstem_data.users.by_id(235).name).to eq('name')
+
+# Getting an array of all ids of in a collection without map
+expect(brainstem_data.users.ids).to include(1)
+
+# Accessing the keys of a collection
+expect(brainstem_data.users.first.keys).to =~ %w(id name email address)
+
+# Using standard array methods on a collection to get by index
+expect(brainstem_data.users.first.name).to eq('name')
+expect(brainstem_data.users[2].name).to eq('name')
+```
+
+An alternate syntax for readability might be:
+
+```ruby
+describe 'brainstem_data' do
+  subject { brainstem_data }
+
+  its('users.ids') { should include(1) }
+end
+```
+
 ### Brainstem and Backbone.js
 
 If you're already using Backbone.js, integrating with a Brainstem API is super simple.  Just use the [Brainstem.js](https://github.com/mavenlink/brainstem-js) gem (or its JavaScript contents) to access your relational Brainstem API from JavaScript.

data/brainstem.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Brainstem::VERSION
 
-  gem.add_dependency "activerecord", ">= 3.0"
+  gem.add_dependency "activerecord", ">= 3.2"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "redcarpet" # for markdown in yard

data/lib/brainstem.rb

@@ -5,7 +5,6 @@ require "brainstem/controller_methods"
 
 # The Brainstem module itself contains a +default_namespace+ class attribute and a few helpers that make managing +PresenterCollections+ and their corresponding namespaces easier.
 module Brainstem
-
   # Sets {default_namespace} to a new value.
   # @param [String] namespace
   # @return [String] the new default namespace
@@ -59,5 +58,4 @@ module Brainstem
   def self.logger=(logger)
     @logger = logger
   end
-
 end

data/lib/brainstem/association_field.rb

@@ -6,6 +6,11 @@ module Brainstem
     # @return [String] The name of the method that is being proxied.
     attr_reader :method_name
 
+    # @!attribute [rw] ignore_type
+    # @return [Boolean] When true, polymorphic associations will be treated like normal ones,
+    #                   skipping the _ref structure and simply using [json_name]_id.
+    attr_accessor :ignore_type
+
     # @!attribute [rw] json_name
     # @return [String] The name of the top-level JSON key for objects provided by this association.
     attr_accessor :json_name
@@ -25,6 +30,7 @@ module Brainstem
       options = args.last.is_a?(Hash) ? args.pop : {}
       method_name = args.first.to_sym if args.first.is_a?(String) || args.first.is_a?(Symbol)
       @json_name = options[:json_name]
+      @ignore_type = options[:ignore_type] || false
       @restrict_to_only = options[:restrict_to_only] || false
       if block_given?
         raise ArgumentError, "options[:json_name] is required when using a block" unless options[:json_name]

data/lib/brainstem/controller_methods.rb

@@ -27,7 +27,7 @@ module Brainstem
     #                           only required if the name cannot be inferred.
     # @return (see PresenterCollection#presenting)
     def present_object(objects, options = {})
-      options.merge!(:params => params)
+      options.merge!(:params => params, :apply_default_filters => false)
 
       if objects.is_a?(ActiveRecord::Relation) || objects.is_a?(Array)
         raise ActiveRecord::RecordNotFound if objects.empty?

data/lib/brainstem/presenter.rb

@@ -155,10 +155,18 @@ module Brainstem
           id_attr = value.method_name ? "#{value.method_name}_id" : nil
 
           if id_attr && model.class.columns_hash.has_key?(id_attr)
-            struct["#{key}_id".to_sym] = to_s_except_nil(model.send(id_attr))
-            reflection = value.method_name && model.reflections[value.method_name.to_sym]
-            if reflection && reflection.options[:polymorphic]
-              struct["#{key.to_s.singularize}_type".to_sym] = model.send("#{value.method_name}_type")
+            reflection = value.method_name && model.class.reflections[value.method_name.to_sym]
+            if reflection && reflection.options[:polymorphic] && !value.ignore_type
+              struct["#{key.to_s.singularize}_ref".to_sym] = begin
+                if (id_attr = model.send(id_attr)).present?
+                  {
+                    :id => to_s_except_nil(id_attr),
+                    :key => model.send("#{value.method_name}_type").try(:constantize).try(:table_name)
+                  }
+                end
+              end
+            else
+              struct["#{key}_id".to_sym] = to_s_except_nil(model.send(id_attr))
             end
           elsif associations.include?(key.to_s)
             result = value.call(model)