active_model_serializers 0.6.0 → 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e52d190b9a08bf39665a61da10e5c1103b553016
+  data.tar.gz: 5ca66e11bde1221cee716a40b48b71f3f3600a09
+SHA512:
+  metadata.gz: 95648244da95ed7a5d69aa91079a89098864d1fe7d4b7d827caeb3b45e019f4e07ddf563c34ee154eb43e9501ac485ba624e6abef6c131cb8fbf79a9bfefc4b8
+  data.tar.gz: 727fb1fa750281605e22c8830212304eb83ac209c2ab2743e7f8695d763eee5635c97d2db6994678b77620385c50899583fd552eb94ffe821c29d1ba10c5d9cb

data/.travis.yml

@@ -5,25 +5,25 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
+  - ruby-head
   - ree
-  - jruby
-  - rbx
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
 gemfile:
   - Gemfile
-  - gemfiles/Gemfile.edge-rails
+  - Gemfile.edge
 matrix:
   exclude:
     # Edge Rails is only compatible with 1.9.3
-    - gemfile: gemfiles/Gemfile.edge-rails
+    - gemfile: Gemfile.edge
       rvm: 1.8.7
-    - gemfile: gemfiles/Gemfile.edge-rails
+    - gemfile: Gemfile.edge
       rvm: 1.9.2
-    - gemfile: gemfiles/Gemfile.edge-rails
+    - gemfile: Gemfile.edge
       rvm: ree
-    - gemfile: gemfiles/Gemfile.edge-rails
-      rvm: jruby
-    - gemfile: gemfiles/Gemfile.edge-rails
-      rvm: rbx
-  allow_failures:
-    - gemfile: gemfiles/Gemfile.edge-rails
-      rvm: 1.9.3
+    - gemfile: Gemfile.edge
+      rvm: jruby-18mode
+    - gemfile: Gemfile.edge
+      rvm: rbx-18mode

data/{gemfiles/Gemfile.edge-rails → Gemfile.edge}

@@ -1,6 +1,6 @@
 source 'http://rubygems.org'
 
-gemspec :path => '..'
+gemspec
 
 gem 'rails', github: 'rails/rails'
 

data/README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://secure.travis-ci.org/josevalim/active_model_serializers.png)](http://travis-ci.org/josevalim/active_model_serializers)
+[![Build Status](https://secure.travis-ci.org/rails-api/active_model_serializers.png)](http://travis-ci.org/rails-api/active_model_serializers)
 
 # Purpose
 
@@ -15,11 +15,11 @@ development.**
 
 # Installing Serializers
 
-For now, the easiest way to install `ActiveModel::Serializers` is to add this
+For now, the easiest way to install `ActiveModel::Serializers` is to add it
 to your `Gemfile`:
 
 ```ruby
-gem "active_model_serializers", :git => "git://github.com/josevalim/active_model_serializers.git"
+gem "active_model_serializers", "~> 0.6.0"
 ```
 
 Then, install it on the command line:
@@ -34,7 +34,7 @@ The easiest way to create a new serializer is to generate a new resource, which
 will generate a serializer at the same time:
 
 ```
-$ rails g resource post title:string body:string 
+$ rails g resource post title:string body:string
 ```
 
 This will generate a serializer in `app/serializers/post_serializer.rb` for
@@ -45,6 +45,14 @@ the serializer generator:
 $ rails g serializer post
 ```
 
+### Support for PORO's and other ORM's.
+
+Currently `ActiveModel::Serializers` adds serialization support to all models
+that descend from `ActiveRecord`. If you are using another ORM or if you are
+using objects that are `ActiveModel` compliant, but do not descend from
+`ActiveRecord`. You must add an include statement for
+`ActiveModel::SerializerSupport`.
+
 # ActiveModel::Serializer
 
 All new serializers descend from ActiveModel::Serializer
@@ -64,7 +72,7 @@ end
 ```
 
 In this case, Rails will look for a serializer named `PostSerializer`, and if
-it exists, use it to serialize the `Post`. 
+it exists, use it to serialize the `Post`.
 
 This also works with `respond_with`, which uses `to_json` under the hood. Also
 note that any options passed to `render :json` will be passed to your
@@ -132,7 +140,9 @@ more concise json. To disable the root element for arrays, you have 3 options:
 #### 1. Disable root globally for in `ArraySerializer`. In an initializer:
 
 ```ruby
-ActiveModel::ArraySerializer.root = false
+ActiveSupport.on_load(:active_model_serializers) do
+  ActiveModel::ArraySerializer.root = false
+end
 ```
 
 #### 2. Disable root per render call in your controller:
@@ -167,6 +177,19 @@ To specify a custom serializer for the items within an array:
 ```ruby
 render :json => @posts, :each_serializer => FancyPostSerializer
 ```
+#### 4. Define default_serializer_options in your controller
+
+If you define `default_serializer_options` method in your controller,
+all serializers in actions of this controller and it's children will use them.
+One of options may be `root: false`
+
+```ruby
+def default_serializer_options
+  {
+    root: false
+  }
+end
+```
 
 ## Getting the old version
 
@@ -207,8 +230,7 @@ end
 ```
 
 Within a serializer's methods, you can access the object being
-serialized as either `object` or the name of the serialized object
-(e.g. `admin_comment` for the `AdminCommentSerializer`).
+serialized as `object`.
 
 You can also access the `scope` method, which provides an
 authorization context to your serializer. By default, scope
@@ -243,6 +265,43 @@ class PostSerializer < ActiveModel::Serializer
 end
 ```
 
+If you would like to add meta information to the outputted JSON, use the `:meta`
+option:
+
+```ruby
+render :json => @posts, :serializer => CustomArraySerializer, :meta => {:total => 10}
+```
+
+The above usage of `:meta` will produce the following:
+
+```json
+{
+  "meta": { "total": 10 },
+  "posts": [
+    { "title": "Post 1", "body": "Hello!" },
+    { "title": "Post 2", "body": "Goodbye!" }
+  ]
+}
+```
+
+If you would like to change the meta key name you can use the `:meta_key` option:
+
+```ruby
+render :json => @posts, :serializer => CustomArraySerializer, :meta => {:total => 10}, :meta_key => 'meta_object'
+```
+
+The above usage of `:meta_key` will produce the following:
+
+```json
+{
+  "meta_object": { "total": 10 },
+  "posts": [
+    { "title": "Post 1", "body": "Hello!" },
+    { "title": "Post 2", "body": "Goodbye!" }
+  ]
+}
+```
+
 If you would like direct, low-level control of attribute serialization, you can
 completely override the `attributes` method to return the hash you need:
 
@@ -280,7 +339,7 @@ class PostSerializer < ActiveModel::Serializer
 
   # only let the user see comments he created.
   def comments
-    post.comments.where(:created_by => scope)
+    object.comments.where(:created_by => scope)
   end
 end
 ```
@@ -307,7 +366,7 @@ class PostSerializer < ActiveModel::Serializer
   has_many :comments
 
   def include_comments?
-    !post.comments_disabled?
+    !object.comments_disabled?
   end
 end
 ```
@@ -376,7 +435,7 @@ Now, any associations will be supplied as an Array of IDs:
     "id": 1,
     "title": "New post",
     "body": "A body!",
-    "comments": [ 1, 2, 3 ]
+    "comment_ids": [ 1, 2, 3 ]
   }
 }
 ```
@@ -386,7 +445,7 @@ Alternatively, you can choose to embed only the ids or the associated objects pe
 ```ruby
 class PostSerializer < ActiveModel::Serializer
   attributes :id, :title, :body
-  
+
   has_many :comments, embed: :objects
   has_many :tags, embed: :ids
 end
@@ -403,7 +462,7 @@ The JSON will look like this:
     "comments": [
       { "id": 1, "body": "what a dumb post" }
     ],
-    "tags": [ 1, 2, 3 ]
+    "tag_ids": [ 1, 2, 3 ]
   }
 }
 ```
@@ -434,11 +493,11 @@ this:
     "id": 1,
     "title": "New post",
     "body": "A body!",
-    "comments": [ 1, 2 ]
+    "comment_ids": [ 1, 2 ]
   },
   "comments": [
-    { "id": 1, "body": "what a dumb post", "tags": [ 1, 2 ] },
-    { "id": 2, "body": "i liked it", "tags": [ 1, 3 ] },
+    { "id": 1, "body": "what a dumb post", "tag_ids": [ 1, 2 ] },
+    { "id": 2, "body": "i liked it", "tag_ids": [ 1, 3 ] },
   ],
   "tags": [
     { "id": 1, "name": "short" },
@@ -476,6 +535,34 @@ This would generate JSON that would look like this:
 }
 ```
 
+You can also specify a different attribute to use rather than the ID of the
+objects:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  embed :ids, :include => true
+
+  attributes :id, :title, :body
+  has_many :comments, :embed_key => :external_id
+end
+```
+
+This would generate JSON that would look like this:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "comment_ids": [ "COMM001" ]
+  },
+  "comments": [
+    { "id": 1, "external_id": "COMM001", "body": "what a dumb post" }
+  ]
+}
+```
+
 **NOTE**: The `embed :ids` mechanism is primary useful for clients that process
 data in bulk and load it into a local store. For these clients, the ability to
 easily see all of the data per type, rather than having to recursively scan the
@@ -496,3 +583,41 @@ class ApplicationController < ActionController::Base
   serialization_scope :current_admin
 end
 ```
+
+Please note that, until now, `serialization_scope` doesn't accept a second
+object with options for specifying which actions should or should not take a
+given scope in consideration.
+
+To be clear, it's not possible, yet, to do something like this:
+
+```ruby
+class SomeController < ApplicationController
+  serialization_scope :current_admin, :except => [:index, :show]
+end
+```
+
+So, in order to have a fine grained control of what each action should take in
+consideration for its scope, you may use something like this:
+
+```ruby
+class CitiesController < ApplicationController
+  serialization_scope nil
+
+  def index
+    @cities = City.all
+
+    render :json => @cities, :each_serializer => CitySerializer
+  end
+
+  def show
+    @city = City.find(params[:id])
+
+    render :json => @city, :scope => current_admin?
+  end
+end
+```
+
+Assuming that the `current_admin?` method needs to make a query in the database
+for the current user, the advantage of this approach is that, by setting
+`serialization_scope` to `nil`, the `index` action no longer will need to make
+that query, only the `show` action will.

data/RELEASE_NOTES.md

@@ -1,4 +1,4 @@
-# VERSION 0.6 (Oct 22, 2012)
+# VERSION 0.6 (to be released)
 
 * Serialize sets properly
 * Add root option to ArraySerializer

data/lib/action_controller/serialization.rb

@@ -40,10 +40,17 @@ module ActionController
     end
 
     def _render_option_json(json, options)
+      options = default_serializer_options.merge(options) if default_serializer_options
+
       serializer = options.delete(:serializer) ||
         (json.respond_to?(:active_model_serializer) && json.active_model_serializer)
 
       if json.respond_to?(:to_ary)
+        unless serializer <= ActiveModel::ArraySerializer
+          raise ArgumentError.new("#{serializer.name} is not an ArraySerializer. " +
+             "You may want to use the :each_serializer option instead.")
+        end
+
         if options[:root] != false && serializer.root != false
           # default root element for arrays is serializer's root or the controller name
           # the serializer for an Array is ActiveModel::ArraySerializer
@@ -54,7 +61,7 @@ module ActionController
       if serializer
         options[:scope] = serialization_scope unless options.has_key?(:scope)
         options[:url_options] = url_options
-        json = serializer.new(json, options.merge(default_serializer_options || {}))
+        json = serializer.new(json, options)
       end
       super
     end

data/lib/active_model/array_serializer.rb

@@ -1,4 +1,6 @@
 require "active_support/core_ext/class/attribute"
+require 'active_support/dependencies'
+require 'active_support/descendants_tracker'
 
 module ActiveModel
   # Active Model Array Serializer
@@ -11,6 +13,8 @@ module ActiveModel
   #     ActiveModel::ArraySerializer.root = false
   #
   class ArraySerializer
+    extend ActiveSupport::DescendantsTracker
+
     attr_reader :object, :options
 
     class_attribute :root
@@ -27,30 +31,34 @@ module ActiveModel
           serializer = item.active_model_serializer
         end
 
-        if serializer
-          serializer.new(item, @options)
+        serializable = serializer ? serializer.new(item, @options) : item
+
+        if serializable.respond_to?(:serializable_hash)
+          serializable.serializable_hash
         else
-          item
+          serializable.as_json
         end
       end
     end
 
+    def meta_key
+      @options[:meta_key].try(:to_sym) || :meta
+    end
+
+    def include_meta(hash)
+      hash[meta_key] = @options[:meta] if @options.has_key?(:meta)
+    end
+
     def as_json(*args)
       @options[:hash] = hash = {}
       @options[:unique_values] = {}
 
-      array = serializable_array.map do |item|
-        if item.respond_to?(:serializable_hash)
-          item.serializable_hash
-        else
-          item.as_json
-        end
-      end
-
       if root = @options[:root]
-        hash.merge!(root => array)
+        hash.merge!(root => serializable_array)
+        include_meta hash
+        hash
       else
-        array
+        serializable_array
       end
     end
   end

data/lib/active_model/serializer.rb

@@ -1,6 +1,7 @@
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/module/anonymous"
-require "set"
+require 'active_support/dependencies'
+require 'active_support/descendants_tracker'
 
 module ActiveModel
   # Active Model Serializer
@@ -37,6 +38,8 @@ module ActiveModel
   #     end
   #
   class Serializer
+    extend ActiveSupport::DescendantsTracker
+
     INCLUDE_METHODS = {}
     INSTRUMENT = { :serialize => :"serialize.serializer", :associations => :"associations.serializer" }
 
@@ -52,178 +55,6 @@ module ActiveModel
       end
     end
 
-    module Associations #:nodoc:
-      class Config #:nodoc:
-        class_attribute :options
-
-        def self.refine(name, class_options)
-          current_class = self
-
-          Class.new(self) do
-            singleton_class.class_eval do
-              define_method(:to_s) do
-                "(subclass of #{current_class.name})"
-              end
-
-              alias inspect to_s
-            end
-
-            self.options = class_options
-          end
-        end
-
-        self.options = {}
-
-        def initialize(name, source, options={})
-          @name = name
-          @source = source
-          @options = options
-        end
-
-        def option(key, default=nil)
-          if @options.key?(key)
-            @options[key]
-          elsif self.class.options.key?(key)
-            self.class.options[key]
-          else
-            default
-          end
-        end
-
-        def target_serializer
-          option(:serializer)
-        end
-
-        def source_serializer
-          @source
-        end
-
-        def key
-          option(:key) || @name
-        end
-
-        def root
-          option(:root) || plural_key
-        end
-
-        def name
-          option(:name) || @name
-        end
-
-        def associated_object
-          option(:value) || source_serializer.send(name)
-        end
-
-        def embed_ids?
-          option(:embed, source_serializer._embed) == :ids
-        end
-
-        def embed_objects?
-          option(:embed, source_serializer._embed) == :objects
-        end
-
-        def embed_in_root?
-          option(:include, source_serializer._root_embed)
-        end
-
-        def embeddable?
-          !associated_object.nil?
-        end
-
-      protected
-
-        def find_serializable(object)
-          if target_serializer
-            target_serializer.new(object, source_serializer.options)
-          elsif object.respond_to?(:active_model_serializer) && (ams = object.active_model_serializer)
-            ams.new(object, source_serializer.options)
-          else
-            object
-          end
-        end
-      end
-
-      class HasMany < Config #:nodoc:
-        alias plural_key key
-
-        def serialize
-          associated_object.map do |item|
-            find_serializable(item).serializable_hash
-          end
-        end
-        alias serialize_many serialize
-
-        def serialize_ids
-          # Use pluck or select_columns if available
-          # return collection.ids if collection.respond_to?(:ids)
-
-          associated_object.map do |item|
-            item.read_attribute_for_serialization(:id)
-          end
-        end
-      end
-
-      class HasOne < Config #:nodoc:
-        def embeddable?
-          if polymorphic? && associated_object.nil?
-            false
-          else
-            true
-          end
-        end
-
-        def polymorphic?
-          option :polymorphic
-        end
-
-        def polymorphic_key
-          associated_object.class.to_s.demodulize.underscore.to_sym
-        end
-
-        def plural_key
-          if polymorphic?
-            associated_object.class.to_s.pluralize.demodulize.underscore.to_sym
-          else
-            key.to_s.pluralize.to_sym
-          end
-        end
-
-        def serialize
-          object = associated_object
-
-          if object && polymorphic?
-            { 
-              :type => polymorphic_key,
-              polymorphic_key => find_serializable(object).serializable_hash
-            }
-          elsif object
-            find_serializable(object).serializable_hash
-          end
-        end
-
-        def serialize_many
-          object = associated_object
-          value = object && find_serializable(object).serializable_hash
-          value ? [value] : []
-        end
-
-        def serialize_ids
-          object = associated_object
-
-          if object && polymorphic?
-            { 
-              :type => polymorphic_key,
-              :id => object.read_attribute_for_serialization(:id)
-            }
-          elsif object
-            object.read_attribute_for_serialization(:id)
-          else
-            nil
-          end
-        end
-      end
-    end
-
     class_attribute :_attributes
     self._attributes = {}
 
@@ -238,10 +69,15 @@ module ActiveModel
     class << self
       # Define attributes to be used in the serialization.
       def attributes(*attrs)
+
         self._attributes = _attributes.dup
 
         attrs.each do |attr|
-          attribute attr
+          if Hash === attr
+            attr.each {|attr_real, key| attribute attr_real, :key => key }
+          else
+            attribute attr
+          end
         end
       end
 
@@ -342,16 +178,31 @@ module ActiveModel
         klass = model_class
         columns = klass.columns_hash
 
-        attrs = _attributes.inject({}) do |hash, (name,key)|
-          column = columns[name.to_s]
-          hash.merge key => column.type
+        attrs = {}
+        _attributes.each do |name, key|
+          if column = columns[name.to_s]
+            attrs[key] = column.type
+          else
+            # Computed attribute (method on serializer or model). We cannot
+            # infer the type, so we put nil.
+            attrs[key] = nil
+          end
         end
 
-        associations = _associations.inject({}) do |hash, (attr,association_class)|
+        associations = {}
+        _associations.each do |attr, association_class|
           association = association_class.new(attr, self)
 
-          model_association = klass.reflect_on_association(association.name)
-          hash.merge association.key => { model_association.macro => model_association.name }
+          if model_association = klass.reflect_on_association(association.name)
+            # Real association.
+            associations[association.key] = { model_association.macro => model_association.name }
+          else
+            # Computed association. We could infer has_many vs. has_one from
+            # the association class, but that would make it different from
+            # real associations, which read has_one vs. belongs_to from the
+            # model.
+            associations[association.key] = nil
+          end
         end
 
         { :attributes => attrs, :associations => associations }
@@ -377,16 +228,7 @@ module ActiveModel
       def root(name)
         self._root = name
       end
-
-      def inherited(klass) #:nodoc:
-        return if klass.anonymous?
-        name = klass.name.demodulize.underscore.sub(/_serializer$/, '')
-
-        klass.class_eval do
-          alias_method name.to_sym, :object
-          root name.to_sym unless self._root == false
-        end
-      end
+      alias_method :root=, :root
     end
 
     attr_reader :object, :options
@@ -395,18 +237,34 @@ module ActiveModel
       @object, @options = object, options
     end
 
+    def root_name
+      return false if self._root == false
+      
+      class_name = self.class.name.demodulize.underscore.sub(/_serializer$/, '').to_sym unless self.class.name.blank?
+      self._root || class_name
+    end
+
     def url_options
       @options[:url_options] || {}
     end
 
+    def meta_key
+      @options[:meta_key].try(:to_sym) || :meta
+    end
+
+    def include_meta(hash)
+      hash[meta_key] = @options[:meta] if @options.has_key?(:meta)
+    end
+
     # Returns a json representation of the serializable
     # object including the root.
     def as_json(options={})
-      if root = options.fetch(:root, @options.fetch(:root, _root))
+      if root = options.fetch(:root, @options.fetch(:root, root_name))
         @options[:hash] = hash = {}
         @options[:unique_values] = {}
 
         hash.merge!(root => serializable_hash)
+        include_meta hash
         hash
       else
         serializable_hash
@@ -416,6 +274,7 @@ module ActiveModel
     # Returns a hash representation of the serializable
     # object without the root.
     def serializable_hash
+      return nil if @object.nil?
       instrument(:serialize, :serializer => self.class.name) do
         @node = attributes
         instrument :associations do
@@ -482,7 +341,7 @@ module ActiveModel
         if association.embed_in_root? && hash.nil?
           raise IncludeError.new(self.class, association.name)
         elsif association.embed_in_root? && association.embeddable?
-          merge_association hash, association.root, association.serialize_many, unique_values
+          merge_association hash, association.root, association.serializables, unique_values
         end
       elsif association.embed_objects?
         node[association.key] = association.serialize
@@ -498,13 +357,15 @@ module ActiveModel
     # a unique list of all of the objects that are already in the Array. This
     # avoids the need to scan through the Array looking for entries every time
     # we want to merge a new list of values.
-    def merge_association(hash, key, value, unique_values)
-      if current_value = unique_values[key]
-        current_value.merge! value
-        hash[key] = current_value.to_a
-      elsif value
-        hash[key] = value
-        unique_values[key] = OrderedSet.new(value)
+    def merge_association(hash, key, serializables, unique_values)
+      already_serialized = (unique_values[key] ||= {})
+      serializable_hashes = (hash[key] ||= [])
+
+      serializables.each do |serializable|
+        unless already_serialized.include? serializable.object
+          already_serialized[serializable.object] = true
+          serializable_hashes << serializable.serializable_hash
+        end
       end
     end