active_model_serializers 0.5.2 → 0.6.0

data/.travis.yml

@@ -1,7 +1,29 @@
+language: ruby
+before_install:
+  - gem install bundler
 rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
   - ree
   - jruby
-  - rbx
+  - rbx
+gemfile:
+  - Gemfile
+  - gemfiles/Gemfile.edge-rails
+matrix:
+  exclude:
+    # Edge Rails is only compatible with 1.9.3
+    - gemfile: gemfiles/Gemfile.edge-rails
+      rvm: 1.8.7
+    - gemfile: gemfiles/Gemfile.edge-rails
+      rvm: 1.9.2
+    - gemfile: gemfiles/Gemfile.edge-rails
+      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

data/Gemfile

@@ -1,7 +1,4 @@
 source 'http://rubygems.org'
 
-# Specify your gem's dependencies in active_model_serializers.gemspec
+# Specify gem dependencies in active_model_serializers.gemspec
 gemspec
-
-gem "pry"
-gem "simplecov", :require => false

data/{README.markdown → README.md}

@@ -39,7 +39,7 @@ $ rails g resource post title:string body:string
 
 This will generate a serializer in `app/serializers/post_serializer.rb` for
 your new model. You can also generate a serializer for an existing model with
-the `serializer generator`:
+the serializer generator:
 
 ```
 $ rails g serializer post
@@ -66,10 +66,108 @@ end
 In this case, Rails will look for a serializer named `PostSerializer`, and if
 it exists, use it to serialize the `Post`. 
 
-This also works with `render_with`, which uses `to_json` under the hood. Also
+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
 serializer and available as `@options` inside.
 
+To specify a custom serializer for an object, there are 2 options:
+
+#### 1. Specify the serializer in your model:
+
+```ruby
+class Post < ActiveRecord::Base
+  def active_model_serializer
+    FancyPostSerializer
+  end
+end
+```
+
+#### 2. Specify the serializer when you render the object:
+
+```ruby
+render :json => @post, :serializer => FancyPostSerializer
+```
+
+## Arrays
+
+In your controllers, when you use `render :json` for an array of objects, AMS will
+use `ActiveModel::ArraySerializer` (included in this project) as the base serializer,
+and the individual `Serializer` for the objects contained in that array.
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+end
+
+class PostsController < ApplicationController
+  def index
+    @posts = Post.all
+    render :json => @posts
+  end
+end
+```
+
+Given the example above, the index action will return
+
+```json
+{
+  "posts":
+    [
+      { "title": "Post 1", "body": "Hello!" },
+      { "title": "Post 2", "body": "Goodbye!" }
+    ]
+}
+```
+
+By default, the root element is the name of the controller. For example, `PostsController`
+generates a root element "posts". To change it:
+
+```ruby
+render :json => @posts, :root => "some_posts"
+```
+
+You may disable the root element for arrays at the top level, which will result in
+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
+```
+
+#### 2. Disable root per render call in your controller:
+
+```ruby
+render :json => @posts, :root => false
+```
+
+#### 3. Create a custom `ArraySerializer` and render arrays with it:
+
+```ruby
+class CustomArraySerializer < ActiveModel::ArraySerializer
+  self.root = false
+end
+
+# controller:
+render :json => @posts, :serializer => CustomArraySerializer
+```
+
+Disabling the root element of the array with any of the above 3 methods
+will produce
+
+```json
+[
+  { "title": "Post 1", "body": "Hello!" },
+  { "title": "Post 2", "body": "Goodbye!" }
+]
+```
+
+To specify a custom serializer for the items within an array:
+
+```ruby
+render :json => @posts, :each_serializer => FancyPostSerializer
+```
+
 ## Getting the old version
 
 If you find that your project is already relying on the old rails to_json
@@ -89,11 +187,49 @@ end
 
 ## Attributes
 
-For specified attributes, the serializer will look up the attribute on the
+For specified attributes, a serializer will look up the attribute on the
 object you passed to `render :json`. It uses
 `read_attribute_for_serialization`, which `ActiveRecord` objects implement as a
 regular attribute lookup.
 
+Before looking up the attribute on the object, a serializer will check for the
+presence of a method with the name of the attribute. This allows serializers to
+include properties beyond the simple attributes of the model. For example:
+
+```ruby
+class PersonSerializer < ActiveModel::Serializer
+  attributes :first_name, :last_name, :full_name
+
+  def full_name
+    "#{object.first_name} #{object.last_name}"
+  end
+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`).
+
+You can also access the `scope` method, which provides an
+authorization context to your serializer. By default, scope
+is the current user of your application, but this
+[can be customized](#customizing-scope).
+
+Serializers will check for the presence of a method named
+`include_[ATTRIBUTE]?` to determine whether a particular attribute should be
+included in the output. This is typically used to customize output
+based on `scope`. For example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body, :author
+
+  def include_author?
+    scope.admin?
+  end
+end
+```
+
 If you would like the key in the outputted JSON to be different from its name
 in ActiveRecord, you can use the `:key` option to customize it:
 
@@ -107,6 +243,24 @@ class PostSerializer < ActiveModel::Serializer
 end
 ```
 
+If you would like direct, low-level control of attribute serialization, you can
+completely override the `attributes` method to return the hash you need:
+
+```ruby
+class PersonSerializer < ActiveModel::Serializer
+  attributes :first_name, :last_name
+
+  def attributes
+    hash = super
+    if scope.admin?
+      hash["ssn"] = object.ssn
+      hash["secret"] = object.mothers_maiden_name
+    end
+    hash
+  end
+end
+```
+
 ## Associations
 
 For specified associations, the serializer will look up the association and
@@ -126,16 +280,12 @@ class PostSerializer < ActiveModel::Serializer
 
   # only let the user see comments he created.
   def comments
-    post.comments.where(:created_by => options[:scope])
+    post.comments.where(:created_by => scope)
   end
 end
 ```
 
-In a serializer, `options[:scope]` is the current authorization scope (usually
-`current_user`), which the controller gives to the serializer when you call
-`render :json`
-
-As with attributes, you can also change the JSON key that the serializer should
+As with attributes, you can change the JSON key that the serializer should
 use for a particular association.
 
 ```ruby
@@ -147,6 +297,44 @@ class PostSerializer < ActiveModel::Serializer
 end
 ```
 
+Also, as with attributes, serializers will check for the presence
+of a method named `include_[ASSOCIATION]?` to determine whether a particular association
+should be included in the output. For example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+  has_many :comments
+
+  def include_comments?
+    !post.comments_disabled?
+  end
+end
+```
+
+If you would like lower-level control of association serialization, you can
+override `include_associations!` to specify which associations should be included:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+  has_one :author
+  has_many :comments
+
+  def include_associations!
+    include! :author if scope.admin?
+    include! :comments unless object.comments_disabled?
+  end
+end
+```
+
+You may also use the `:serializer` option to specify a custom serializer class and the `:polymorphic` option to specify an association that is polymorphic (STI), e.g.:
+
+```ruby
+  has_many :comments, :serializer => CommentShortSerializer
+  has_one :reviewer, :polymorphic => true
+```
+
 ## Embedding Associations
 
 By default, associations will be embedded inside the serialized object. So if
@@ -193,6 +381,33 @@ Now, any associations will be supplied as an Array of IDs:
 }
 ```
 
+Alternatively, you can choose to embed only the ids or the associated objects per association:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+  
+  has_many :comments, embed: :objects
+  has_many :tags, embed: :ids
+end
+```
+
+The JSON will look like this:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "comments": [
+      { "id": 1, "body": "what a dumb post" }
+    ],
+    "tags": [ 1, 2, 3 ]
+  }
+}
+```
+
 In addition to supplying an Array of IDs, you may want to side-load the data
 alongside the main object. This makes it easier to process the entire package
 of data without having to recursively scan the tree looking for embedded
@@ -268,3 +483,16 @@ data looking for information, is extremely useful.
 
 If you are mostly working with the data in simple scenarios and manually making
 Ajax requests, you probably just want to use the default embedded behavior.
+
+## Customizing Scope
+
+In a serializer, `scope` is the current authorization scope which the controller
+provides to the serializer when you call `render :json`. By default, this is
+`current_user`, but can be customized in your controller by calling
+`serialization_scope`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  serialization_scope :current_admin
+end
+```

data/RELEASE_NOTES.md

@@ -1,3 +1,14 @@
+# VERSION 0.6 (Oct 22, 2012)
+
+* Serialize sets properly
+* Add root option to ArraySerializer
+* Support polymorphic associations
+* Support :each_serializer in ArraySerializer
+* Add `scope` method to easily access the scope in the serializer
+* Fix regression with Rails 3.2.6; add Rails 4 support
+* Allow serialization_scope to be disabled with serialization_scope nil
+* Array serializer should support pure ruby objects besides serializers
+
 # VERSION 0.5 (May 16, 2012)
 
 * First tagged version

data/active_model_serializers.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |gem|
   gem.email         = ["jose.valim@gmail.com", "wycats@gmail.com"]
   gem.description   = %q{Making it easy to serialize models for client-side use}
   gem.summary       = %q{Bringing consistency and object orientation to model serialization. Works great for client-side MVC frameworks!}
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/josevalim/active_model_serializers"
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   gem.files         = `git ls-files`.split("\n")
@@ -17,6 +17,8 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = ActiveModel::Serializer::VERSION
 
-  gem.add_dependency 'activemodel', '~> 3.0'
-  gem.add_development_dependency "rails", "~> 3.0"
+  gem.add_dependency 'activemodel', '>= 3.0'
+  gem.add_development_dependency "rails", ">= 3.0"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "simplecov"
 end

data/cruft.md

@@ -0,0 +1,19 @@
+As of Ruby 1.9.3, it is impossible to dynamically generate a Symbol
+through interpolation without generating garbage. Theoretically, Ruby
+should be able to take care of this by building up the String in C and
+interning the C String.
+
+Because of this, we avoid generating dynamic Symbols at runtime. For
+example, instead of generating the instrumentation event dynamically, we
+have a constant with a Hash of events:
+
+```ruby
+INSTRUMENT = {
+  :serialize => :"serialize.serializer",
+  :associations => :"associations.serializer"
+}
+```
+
+If Ruby ever fixes this issue and avoids generating garbage with dynamic
+symbols, this code can be removed.
+

data/gemfiles/Gemfile.edge-rails

@@ -0,0 +1,9 @@
+source 'http://rubygems.org'
+
+gemspec :path => '..'
+
+gem 'rails', github: 'rails/rails'
+
+# Current dependencies of edge rails
+gem 'journey', github: 'rails/journey'
+gem 'activerecord-deprecated_finders' , github: 'rails/activerecord-deprecated_finders'

data/lib/action_controller/serialization.rb

@@ -33,22 +33,26 @@ module ActionController
     end
 
     def serialization_scope
-      send(_serialization_scope) if respond_to?(_serialization_scope)
+      send(_serialization_scope) if _serialization_scope && respond_to?(_serialization_scope)
     end
 
     def default_serializer_options
     end
 
     def _render_option_json(json, options)
-      if json.respond_to?(:to_ary)
-        options[:root] ||= controller_name unless options[:root] == false
-      end
-
       serializer = options.delete(:serializer) ||
         (json.respond_to?(:active_model_serializer) && json.active_model_serializer)
 
+      if json.respond_to?(:to_ary)
+        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
+          options[:root] ||= serializer.root || controller_name
+        end
+      end
+
       if serializer
-        options[:scope] = serialization_scope
+        options[:scope] = serialization_scope unless options.has_key?(:scope)
         options[:url_options] = url_options
         json = serializer.new(json, options.merge(default_serializer_options || {}))
       end

data/lib/active_model/array_serializer.rb

@@ -0,0 +1,58 @@
+require "active_support/core_ext/class/attribute"
+
+module ActiveModel
+  # Active Model Array Serializer
+  #
+  # It serializes an Array, checking if each element that implements
+  # the +active_model_serializer+ method.
+  #
+  # To disable serialization of root elements:
+  #
+  #     ActiveModel::ArraySerializer.root = false
+  #
+  class ArraySerializer
+    attr_reader :object, :options
+
+    class_attribute :root
+
+    def initialize(object, options={})
+      @object, @options = object, options
+    end
+
+    def serializable_array
+      @object.map do |item|
+        if @options.has_key? :each_serializer
+          serializer = @options[:each_serializer]
+        elsif item.respond_to?(:active_model_serializer)
+          serializer = item.active_model_serializer
+        end
+
+        if serializer
+          serializer.new(item, @options)
+        else
+          item
+        end
+      end
+    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)
+      else
+        array
+      end
+    end
+  end
+
+end