active_model_serializers 0.9.0.alpha1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aeb402f8407aece224529052410e2ad33485d7eb
-  data.tar.gz: db4621bc2e62921b75a8e02e77b30e4782951b1a
+  metadata.gz: 65701e1dd4ae30a60340c60fa9361c540148bb64
+  data.tar.gz: f7b2b52348b116ac1eea607a51e9ddb8d9c15fce
 SHA512:
-  metadata.gz: 5496e9420a975333a78f239eb2bbeb680f4240ec22e1bdbbe989fceb480325e14fbd96ab706510f0b0297b8317d85298451b034eabb5f1e67627e03bd0aa5c57
-  data.tar.gz: 2320ddcf2bf5c13028669dabc470331008de7e3fe79bf3f4ffb4d70df701731061541ccfc4ed57160dc520b8637e02e75b8510bfb6c72470be4ffd2603618be1
+  metadata.gz: 658d1fadb66a26b4b93a72cdb87498bb89ee83565de5d846ca3e2cdaa913303256e9267627d8e55593aa1696963f255e2fe44918e858ce2e66251710d3694241
+  data.tar.gz: 2b100c2bcb26d9696001eefae6fd3bddc68d779578c2c313f64b06f47cf51024f6e525a7afd70d8afd28d973bb7fd2d9bb7923391d2271233317d2a6669948b0

data/README.md

@@ -1,15 +1,8 @@
-[![Build Status](https://api.travis-ci.org/rails-api/active_model_serializers.png)](https://travis-ci.org/rails-api/active_model_serializers) 
+[![Build Status](https://api.travis-ci.org/rails-api/active_model_serializers.png?branch=0-9-stable)](https://travis-ci.org/rails-api/active_model_serializers) 
 [![Code Climate](https://codeclimate.com/github/rails-api/active_model_serializers.png)](https://codeclimate.com/github/rails-api/active_model_serializers) 
-[![Coverage Status](https://coveralls.io/repos/rails-api/active_model_serializers/badge.png?branch=master)](https://coveralls.io/r/rails-api/active_model_serializers)
 
 # ActiveModel::Serializers
 
-## Master - 0.9.0
-
-**master is under development, there are some incompatible changes with the current stable release.**
-
-If you want to read the stable documentation visit [0.8 README](https://github.com/rails-api/active_model_serializers/blob/0-8-stable/README.md)
-
 ## Purpose
 
 `ActiveModel::Serializers` encapsulates the JSON serialization of objects. 
@@ -67,13 +60,11 @@ $ rails g serializer post
 
 ### Support for POROs
 
-Currently `ActiveModel::Serializers` expects objects to implement
-read\_attribute\_for\_serialization. That's all you need to do to have
-your POROs supported. 
+The PORO should include ActiveModel::SerializerSupport. That's all you need to
+do to have your POROs supported.
 
-# ActiveModel::Serializer
-
-All new serializers descend from ActiveModel::Serializer
+For Rails versions before Rails 4  ActiveModel::Serializers expects objects to
+implement `read_attribute_for_serialization`.
 
 # render :json
 
@@ -158,6 +149,29 @@ To specify a custom serializer for the items within an array:
 render json: @posts, each_serializer: FancyPostSerializer
 ```
 
+## Render independently
+
+By default the setting of serializer is in controller as described above which is the
+recommended way. However, there may be cases you need to render the json object elsewhere
+say in a helper or a view when controller is only for main object.
+
+Then you can render the serialized JSON independently.
+
+```ruby
+def current_user_as_json_helper
+  CurrentUserSerializer.new(current_user).to_json
+end
+```
+
+You can also render an array of objects using ArraySerializer.
+
+```ruby
+def users_array_as_json_helper(users)
+  ActiveModel::ArraySerializer.new(users, each_serializer: UserSerializer).to_json
+end
+```
+
+
 ## Disabling the root element
 
 You have 4 options to disable the root element, each with a slightly different scope:
@@ -205,6 +219,23 @@ def default_serializer_options
 end
 ```
 
+## Changing the Key Format
+
+You can specify that serializers use the lower-camel key format at the config, class or instance level.
+
+```ruby
+
+ActiveModel::Serializer.setup do |config|
+  config.key_format = :lower_camel
+end
+
+class BlogLowerCamelSerializer < ActiveModel::Serializer 
+  format_keys :lower_camel
+end
+
+BlogSerializer.new(object, key_format: :lower_camel)
+```
+
 ## Getting the old version
 
 If you find that your project is already relying on the old rails to_json
@@ -263,7 +294,7 @@ authorization context to your serializer. By default, the context
 is the current user of your application, but this
 [can be customized](#customizing-scope).
 
-Serializers provides a method named `filter`, which should return an array
+Serializers provide a method named `filter`, which should return an array
 used to determine what attributes and associations should be included in the output.
 This is typically used to customize output based on `current_user`. For example:
 
@@ -485,6 +516,33 @@ Now, any associations will be supplied as an Array of IDs:
 }
 ```
 
+You may also choose to embed the IDs by the association's name underneath an
+`embed_key` for the resource. For example, say we want to change `comment_ids`
+to `comments` underneath a `links` key:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+
+  has_many :comments, embed: ids, embed_namespace: :links
+end
+```
+
+The JSON will look like this:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "links": {
+      "comments": [ 1, 2, 3 ]
+    }
+  }
+}
+```
+
 Alternatively, you can choose to embed only the ids or the associated objects per association:
 
 ```ruby
@@ -552,6 +610,42 @@ this:
 }
 ```
 
+If you would like to namespace association JSON underneath a certain key in
+the root document (say, `linked`), you can specify an `embed_in_root_key`:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  embed: ids, include: true, embed_in_root_key: :linked
+
+  attributes: :id, :title, :body
+  has_many :comments, :tags
+end
+```
+
+The above would yield the following JSON document:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "comment_ids": [ 1, 2 ]
+  },
+  "linked": {
+    "comments": [
+      { "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" },
+      { "id": 2, "name": "whiny" },
+      { "id": 3, "name": "happy" }
+    ]
+  }
+}
+```
+
 When side-loading data, your serializer cannot have the `{ root: false }` option, 
 as this would lead to invalid JSON. If you do not have a root key, the `include` 
 instruction will be ignored
@@ -724,6 +818,29 @@ end
 
 The caching interface uses `Rails.cache` under the hood.
 
+# ApplicationSerializer
+
+By default, new serializers descend from ActiveModel::Serializer. However, if you wish to share behaviour across your serializers you can create an ApplicationSerializer at ```app/serializers/application_serializer.rb```:
+
+```ruby
+class ApplicationSerializer < ActiveModel::Serializer
+end
+```
+
+Any newly generated serializers will automatically descend from ApplicationSerializer.
+
+```
+$ rails g serializer post
+```
+
+now generates:
+
+```ruby
+class PostSerializer < ApplicationSerializer
+  attributes :id
+end
+````
+
 # Design and Implementation Guidelines
 
 ## Keep it Simple

data/lib/action_controller/serialization.rb

@@ -29,6 +29,11 @@ module ActionController
 
     include ActionController::Renderers
 
+    class << self
+      attr_accessor :enabled
+    end
+    self.enabled = true
+
     included do
       class_attribute :_serialization_scope
       self._serialization_scope = :current_user

data/lib/action_controller/serialization_test_case.rb

@@ -0,0 +1,79 @@
+module ActionController
+  module SerializationAssertions
+    extend ActiveSupport::Concern
+
+    included do
+      setup :setup_subscriptions
+      teardown :teardown_subscriptions
+    end
+
+    def setup_subscriptions
+      @serializers = Hash.new(0)
+
+      ActiveSupport::Notifications.subscribe("!serialize.active_model_serializers") do |name, start, finish, id, payload|
+        serializer = payload[:serializer]
+        @serializers[serializer] += 1
+      end
+    end
+
+    def teardown_subscriptions
+      ActiveSupport::Notifications.unsubscribe("!serialize.active_model_serializers")
+    end
+
+    def process(*args)
+      @serializers = Hash.new(0)
+      super
+    end
+
+    # Asserts that the request was rendered with the appropriate serializers.
+    #
+    #  # assert that the "PostSerializer" serializer was rendered
+    #  assert_serializer "PostSerializer"
+    #
+    #  # assert that the instance of PostSerializer was rendered
+    #  assert_serializer PostSerializer
+    #
+    #  # assert that the "PostSerializer" serializer was rendered
+    #  assert_serializer :post_serializer
+    #
+    #  # assert that the rendered serializer starts with "Post"
+    #  assert_serializer %r{\APost.+\Z}
+    #
+    #  # assert that no serializer was rendered
+    #  assert_serializer nil
+    #
+    #
+    def assert_serializer(options = {}, message = nil)
+      # Force body to be read in case the template is being streamed.
+      response.body
+
+      rendered = @serializers
+      msg = message || "expecting <#{options.inspect}> but rendering with <#{rendered.keys}>"
+
+      matches_serializer = case options
+                           when lambda { |options| options.kind_of?(Class) && options < ActiveModel::Serializer }
+                             rendered.any? do |serializer, count|
+                               options.name == serializer
+                             end
+                           when Symbol
+                             options = options.to_s.camelize
+                             rendered.any? do |serializer, count|
+                               serializer == options
+                             end
+                           when String
+                             !options.empty? && rendered.any? do |serializer, count|
+                               serializer == options
+                             end
+                           when Regexp
+                             rendered.any? do |serializer, count|
+                               serializer.match(options)
+                             end
+                           when NilClass
+                             rendered.blank?
+                           else
+                             raise ArgumentError, "assert_serializer only accepts a String, Symbol, Regexp, ActiveModel::Serializer, or nil"
+                           end
+      assert matches_serializer, msg
+    end
+  end
+end

data/lib/active_model/array_serializer.rb

@@ -1,6 +1,5 @@
 require 'active_model/default_serializer'
 require 'active_model/serializable'
-require 'active_model/serializer'
 
 module ActiveModel
   class ArraySerializer
@@ -20,20 +19,21 @@ module ActiveModel
       @meta            = options[@meta_key]
       @each_serializer = options[:each_serializer]
       @resource_name   = options[:resource_name]
+      @only            = options[:only] ? Array(options[:only]) : nil
+      @except          = options[:except] ? Array(options[:except]) : nil
+      @key_format      = options[:key_format] || options[:each_serializer].try(:key_format)
     end
-    attr_accessor :object, :scope, :root, :meta_key, :meta
+    attr_accessor :object, :scope, :root, :meta_key, :meta, :key_format
 
     def json_key
-      if root.nil?
-        @resource_name
-      else
-        root
-      end
+      key = root.nil? ? @resource_name : root
+
+      key_format == :lower_camel && key.present? ? key.camelize(:lower) : key
     end
 
     def serializer_for(item)
       serializer_class = @each_serializer || Serializer.serializer_for(item) || DefaultSerializer
-      serializer_class.new(item, scope: scope)
+      serializer_class.new(item, scope: scope, key_format: key_format, only: @only, except: @except)
     end
 
     def serializable_object
@@ -46,6 +46,8 @@ module ActiveModel
     def embedded_in_root_associations
       @object.each_with_object({}) do |item, hash|
         serializer_for(item).embedded_in_root_associations.each_pair do |type, objects|
+          next if !objects || objects.flatten.empty?
+
           if hash.has_key?(type)
             hash[type].concat(objects).uniq!
           else
@@ -54,5 +56,10 @@ module ActiveModel
         end
       end
     end
+
+    private
+    def instrumentation_keys
+      [:object, :scope, :root, :meta_key, :meta, :each_serializer, :resource_name, :key_format]
+    end
   end
 end

data/lib/active_model/default_serializer.rb

@@ -9,14 +9,24 @@ module ActiveModel
 
     attr_reader :object
 
-    def initialize(object, options=nil)
+    def initialize(object, options={})
       @object = object
+      @wrap_in_array = options[:_wrap_in_array]
     end
 
     def as_json(options={})
-      @object.as_json
+      instrument('!serialize') do
+        return [] if @object.nil? && @wrap_in_array
+        hash = @object.as_json
+        @wrap_in_array ? [hash] : hash
+      end
     end
     alias serializable_hash as_json
     alias serializable_object as_json
+
+    private
+    def instrumentation_keys
+      [:object, :wrap_in_array]
+    end
   end
 end

data/lib/active_model/serializable.rb

@@ -1,12 +1,14 @@
 module ActiveModel
   module Serializable
     def as_json(options={})
-      if root = options.fetch(:root, json_key)
-        hash = { root => serializable_object }
-        hash.merge!(serializable_data)
-        hash
-      else
-        serializable_object
+      instrument('!serialize') do
+        if root = options.fetch(:root, json_key)
+          hash = { root => serializable_object }
+          hash.merge!(serializable_data)
+          hash
+        else
+          serializable_object
+        end
       end
     end
 
@@ -21,5 +23,18 @@ module ActiveModel
     def embedded_in_root_associations
       {}
     end
+
+    private
+    def instrument(action, &block)
+      payload = instrumentation_keys.inject({ serializer: self.class.name }) do |payload, key|
+        payload[:payload] = self.instance_variable_get(:"@#{key}")
+        payload
+      end
+      ActiveSupport::Notifications.instrument("#{action}.active_model_serializers", payload, &block)
+    end
+
+    def instrumentation_keys
+      [:object, :scope, :root, :meta_key, :meta, :wrap_in_array, :only, :except, :key_format]
+    end
   end
 end

data/lib/active_model/serializer.rb

@@ -24,9 +24,21 @@ module ActiveModel
         end
       end
 
+      EMBED_IN_ROOT_OPTIONS = [
+        :include,
+        :embed_in_root,
+        :embed_in_root_key,
+        :embed_namespace
+      ].freeze
+
       def embed(type, options={})
         CONFIG.embed = type
-        CONFIG.embed_in_root = true if options[:embed_in_root] || options[:include]
+        if EMBED_IN_ROOT_OPTIONS.any? { |opt| options[opt].present? }
+          CONFIG.embed_in_root = true
+        end
+        if options[:embed_in_root_key].present?
+          CONFIG.embed_in_root_key = options[:embed_in_root_key]
+        end
         ActiveSupport::Deprecation.warn <<-WARN
 ** Notice: embed is deprecated. **
 The use of .embed method on a Serializer will be soon removed, as this should have a global scope and not a class scope.
@@ -38,10 +50,19 @@ end
         WARN
       end
 
+      def format_keys(format)
+        @key_format = format
+      end
+      attr_reader :key_format
+
       if RUBY_VERSION >= '2.0'
         def serializer_for(resource)
           if resource.respond_to?(:to_ary)
-            ArraySerializer
+            if Object.constants.include?(:ArraySerializer)
+              ::ArraySerializer
+            else
+              ArraySerializer
+            end
           else
             begin
               Object.const_get "#{resource.class.name}Serializer"
@@ -53,7 +74,11 @@ end
       else
         def serializer_for(resource)
           if resource.respond_to?(:to_ary)
-            ArraySerializer
+            if Object.constants.include?(:ArraySerializer)
+              ::ArraySerializer
+            else
+              ArraySerializer
+            end
           else
             "#{resource.class.name}Serializer".safe_constantize
           end
@@ -108,15 +133,21 @@ end
       @meta_key      = options[:meta_key] || :meta
       @meta          = options[@meta_key]
       @wrap_in_array = options[:_wrap_in_array]
+      @only          = options[:only] ? Array(options[:only]) : nil
+      @except        = options[:except] ? Array(options[:except]) : nil
+      @key_format    = options[:key_format]
+      @context       = options[:context]
     end
-    attr_accessor :object, :scope, :root, :meta_key, :meta
+    attr_accessor :object, :scope, :root, :meta_key, :meta, :key_format, :context
 
     def json_key
-      if root == true || root.nil?
+      key = if root == true || root.nil?
         self.class.root_name
       else
         root
       end
+
+      key_format == :lower_camel && key.present? ? key.camelize(:lower) : key
     end
 
     def attributes
@@ -131,8 +162,17 @@ end
       associations.each_with_object({}) do |(name, association), hash|
         if included_associations.include? name
           if association.embed_ids?
-            hash[association.key] = serialize_ids association
+            ids = serialize_ids association
+            if association.embed_namespace?
+              hash = hash[association.embed_namespace] ||= {}
+              hash[association.key] = ids
+            else
+              hash[association.key] = ids
+            end
           elsif association.embed_objects?
+            if association.embed_namespace?
+              hash = hash[association.embed_namespace] ||= {}
+            end
             hash[association.embedded_key] = serialize association
           end
         end
@@ -140,7 +180,13 @@ end
     end
 
     def filter(keys)
-      keys
+      if @only
+        keys & @only
+      elsif @except
+        keys - @except
+      else
+        keys
+      end
     end
 
     def embedded_in_root_associations
@@ -149,8 +195,11 @@ end
       associations.each_with_object({}) do |(name, association), hash|
         if included_associations.include? name
           if association.embed_in_root?
+            if association.embed_in_root_key?
+              hash = hash[association.embed_in_root_key] ||= {}
+            end
             association_serializer = build_serializer(association)
-            hash.merge! association_serializer.embedded_in_root_associations
+            hash.merge!(association_serializer.embedded_in_root_associations) {|key, oldval, newval| [newval, oldval].flatten }
 
             serialized_data = association_serializer.serializable_object
             key = association.root_key
@@ -182,12 +231,38 @@ end
       end
     end
 
+    def key_format
+      @key_format || self.class.key_format || CONFIG.key_format
+    end
+
+    def format_key(key)
+      if key_format == :lower_camel
+        key.to_s.camelize(:lower)
+      else
+        key
+      end
+    end
+
+    def convert_keys(hash)
+      Hash[hash.map do |k,v|
+        key = if k.is_a?(Symbol)
+          format_key(k).to_sym
+        else
+          format_key(k)
+        end
+
+        [key ,v]
+      end]
+    end
+
     def serializable_object(options={})
-      return nil if object.nil?
+      return @wrap_in_array ? [] : nil if @object.nil?
       hash = attributes
       hash.merge! associations
+      hash = convert_keys(hash) if key_format.present?
       @wrap_in_array ? [hash] : hash
     end
     alias_method :serializable_hash, :serializable_object
   end
+
 end