active_model_serializers 0.8.3 → 0.9.1

data/README.md

@@ -1,10 +1,13 @@
-[![Build Status](https://api.travis-ci.org/rails-api/active_model_serializers.png)](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)
+[![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)
 
-# Purpose
+# ActiveModel::Serializers
 
-The purpose of `ActiveModel::Serializers` is to provide an object to
-encapsulate serialization of `ActiveModel` objects, including `ActiveRecord`
-objects.
+## Purpose
+
+`ActiveModel::Serializers` encapsulates the JSON serialization of objects.
+Objects that respond to read\_attribute\_for\_serialization
+(including `ActiveModel` and `ActiveRecord` objects) are supported.
 
 Serializers know about both a model and the `current_user`, so you can
 customize serialization based upon whether a user is authorized to see the
@@ -13,13 +16,13 @@ content.
 In short, **serializers replace hash-driven development with object-oriented
 development.**
 
-# Installing Serializers
+# Installing
 
 The easiest way to install `ActiveModel::Serializers` is to add it to your
 `Gemfile`:
 
 ```ruby
-gem "active_model_serializers", "~> 0.8.0"
+gem "active_model_serializers"
 ```
 
 Then, install it on the command line:
@@ -28,6 +31,16 @@ Then, install it on the command line:
 $ bundle install
 ```
 
+#### Ruby 1.8 is no longer supported!
+
+If you must use a ruby 1.8 version (MRI 1.8.7, REE, Rubinius 1.8, or JRuby 1.8), you need to use version 0.8.x.
+Versions after 0.9.0 do not support ruby 1.8. To specify version 0.8, include this in your Gemfile:
+
+```ruby
+gem "active_model_serializers", "~> 0.8.0"
+```
+
+
 # Creating a Serializer
 
 The easiest way to create a new serializer is to generate a new resource, which
@@ -45,21 +58,13 @@ 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` or include `Mongoid::Document`. If you are
-using another ORM, or if you are using objects that are `ActiveModel`
-compliant but do not descend from `ActiveRecord` or include
-`Mongoid::Document`, you must add an include statement for
-`ActiveModel::SerializerSupport` to make models serializable. If you
-also want to make collections serializable, you should include
-`ActiveModel::ArraySerializerSupport` into your ORM's
-relation/criteria class.
+### Support for POROs
 
-# ActiveModel::Serializer
+The PORO should include ActiveModel::SerializerSupport. That's all you need to
+do to have your POROs supported.
 
-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
 
@@ -70,7 +75,7 @@ for a serializer for the object and use it if available.
 class PostsController < ApplicationController
   def show
     @post = Post.find(params[:id])
-    render :json => @post
+    render json: @post
   end
 end
 ```
@@ -82,22 +87,22 @@ 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:
+To specify a custom serializer for an object, you can specify the
+serializer when you render the object:
 
 ```ruby
-class Post < ActiveRecord::Base
-  def active_model_serializer
-    FancyPostSerializer
-  end
-end
+render json: @post, serializer: FancyPostSerializer
 ```
 
-#### 2. Specify the serializer when you render the object:
+### Use serialization outside of ActionController::Base
+
+When controller does not inherit from ActionController::Base,
+include Serialization module manually:
 
 ```ruby
-render :json => @post, :serializer => FancyPostSerializer
+class ApplicationController < ActionController::API
+  include ActionController::Serialization
+end
 ```
 
 ## Arrays
@@ -114,7 +119,7 @@ end
 class PostsController < ApplicationController
   def index
     @posts = Post.all
-    render :json => @posts
+    render json: @posts
   end
 end
 ```
@@ -135,7 +140,7 @@ By default, the root element is the name of the controller. For example, `PostsC
 generates a root element "posts". To change it:
 
 ```ruby
-render :json => @posts, :root => "some_posts"
+render json: @posts, root: "some_posts"
 ```
 
 You may disable the root element for arrays at the top level, which will result in
@@ -152,9 +157,32 @@ root element of the array with any of those methods will produce
 To specify a custom serializer for the items within an array:
 
 ```ruby
-render :json => @posts, :each_serializer => FancyPostSerializer
+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:
@@ -164,19 +192,17 @@ You have 4 options to disable the root element, each with a slightly different s
 In an initializer:
 
 ```ruby
-ActiveSupport.on_load(:active_model_serializers) do
-  # Disable for all serializers (except ArraySerializer)
-  ActiveModel::Serializer.root = false
-  
-  # Disable for ArraySerializer
-  ActiveModel::ArraySerializer.root = false
-end
+# Disable for all serializers (except ArraySerializer)
+ActiveModel::Serializer.root = false
+
+# Disable for ArraySerializer
+ActiveModel::ArraySerializer.root = false
 ```
 
 #### 2. Disable root per render call in your controller
 
 ```ruby
-render :json => @posts, :root => false
+render json: @posts, root: false
 ```
 
 #### 3. Subclass the serializer, and specify using it
@@ -187,7 +213,7 @@ class CustomArraySerializer < ActiveModel::ArraySerializer
 end
 
 # controller:
-render :json => @posts, :serializer => CustomArraySerializer
+render json: @posts, serializer: CustomArraySerializer
 ```
 
 #### 4. Define default_serializer_options in your controller
@@ -204,10 +230,39 @@ 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)
+```
+
+## Changing the default association key type
+
+You can specify that serializers use unsuffixed names as association keys by default.
+
+`````ruby
+ActiveModel::Serializer.setup do |config|
+  config.default_key_type = :name
+end
+````
+
+This will build association keys like `comments` or `author` instead of `comment_ids` or `author_id`.
+
 ## Getting the old version
 
 If you find that your project is already relying on the old rails to_json
-change `render :json` to `render :json => @your_object.to_json`.
+change `render :json` to `render json: @your_object.to_json`.
 
 # Attributes and Associations
 
@@ -245,49 +300,57 @@ end
 Within a serializer's methods, you can access the object being
 serialized as `object`.
 
-You can also access the `current_user` method, which provides an
-authorization context to your serializer. By default, the context
-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 `current_user`. For example:
+Since this shadows any attribute named `object`, you can include them through `object.object`. For example:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body, :author
+class VersionSerializer < ActiveModel::Serializer
+  attributes :version_object
 
-  def include_author?
-    current_user.admin?
+  def version_object
+    object.object
   end
 end
 ```
 
-The type of a computed attribute (like :full_name above) is not easily
-calculated without some sophisticated static code analysis. To specify the
-type of a computed attribute:
+You can also access the `scope` method, which provides an
+authorization context to your serializer. By default, the context
+is the current user of your application, but this
+[can be customized](#customizing-scope).
+
+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:
 
 ```ruby
-class PersonSerializer < ActiveModel::Serializer
-  attributes :first_name, :last_name, {:full_name => :string}
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body, :author
 
-  def full_name
-    "#{object.first_name} #{object.last_name}"
+  def filter(keys)
+    if scope.admin?
+      keys
+    else
+      keys - [:author]
+    end
   end
 end
 ```
 
+And it's also safe to mutate keys argument by doing keys.delete(:author)
+in case you want to avoid creating two extra arrays. Note that if you do an
+in-place modification, you still need to return the modified array.
+
 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:
+in ActiveRecord, you can declare the attribute with the different name
+and redefine that method:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
-  attributes :id, :body
+  # look up subject on the model, but use title in the JSON
+  def title
+    object.subject
+  end
 
-  # look up :subject on the model, but use +title+ in the JSON
-  attribute :subject, :key => :title
+  attributes :id, :body, :title
   has_many :comments
 end
 ```
@@ -296,7 +359,7 @@ 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}
+render json: @posts, serializer: CustomArraySerializer, meta: {total: 10}
 ```
 
 The above usage of `:meta` will produce the following:
@@ -314,7 +377,7 @@ The above usage of `:meta` will produce the following:
 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'
+render json: @posts, serializer: CustomArraySerializer, meta_object: {total: 10}, meta_key: 'meta_object'
 ```
 
 The above usage of `:meta_key` will produce the following:
@@ -329,6 +392,9 @@ The above usage of `:meta_key` will produce the following:
 }
 ```
 
+When using meta information, your serializer cannot have the `{ root: false }` option, as this would lead to
+invalid JSON. If you do not have a root key, the meta information will be ignored.
+
 If you would like direct, low-level control of attribute serialization, you can
 completely override the `attributes` method to return the hash you need:
 
@@ -338,7 +404,7 @@ class PersonSerializer < ActiveModel::Serializer
 
   def attributes
     hash = super
-    if current_user.admin?
+    if scope.admin?
       hash["ssn"] = object.ssn
       hash["secret"] = object.mothers_maiden_name
     end
@@ -357,7 +423,7 @@ and use it to serialize the comment.
 By default, serializers simply look up the association on the original object.
 You can customize this behavior by implementing a method with the name of the
 association and returning a different Array. Often, you will do this to
-customize the objects returned based on the current user.
+customize the objects returned based on the current user (scope).
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
@@ -366,7 +432,7 @@ class PostSerializer < ActiveModel::Serializer
 
   # only let the user see comments he created.
   def comments
-    object.comments.where(:created_by => current_user)
+    object.comments.where(created_by: scope)
   end
 end
 ```
@@ -379,27 +445,27 @@ class PostSerializer < ActiveModel::Serializer
   attributes :id, :title, :body
 
   # look up comments, but use +my_comments+ as the key in JSON
-  has_many :comments, :key => :my_comments
+  has_many :comments, root: :my_comments
 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:
+Also, as with attributes, serializers will execute a filter method to
+determine which associations should be included in the output. For
+example:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
   attributes :id, :title, :body
   has_many :comments
 
-  def include_comments?
-    !object.comments_disabled?
+  def filter(keys)
+    keys.delete :comments if object.comments_disabled?
+    keys
   end
 end
 ```
 
-If you would like lower-level control of association serialization, you can
-override `include_associations!` to specify which associations should be included:
+Or ...
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
@@ -407,9 +473,10 @@ class PostSerializer < ActiveModel::Serializer
   has_one :author
   has_many :comments
 
-  def include_associations!
-    include! :author if current_user.admin?
-    include! :comments unless object.comments_disabled?
+  def filter(keys)
+    keys.delete :author unless scope.admin?
+    keys.delete :comments if object.comments_disabled?
+    keys
   end
 end
 ```
@@ -417,8 +484,8 @@ 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
+  has_many :comments, serializer: CommentShortSerializer
+  has_one :reviewer, polymorphic: true
 ```
 
 Serializers are only concerned with multiplicity, and not ownership. `belongs_to` ActiveRecord associations can be included using `has_one` in your serializer.
@@ -469,6 +536,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 a
+`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, key: :comments, 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
@@ -506,7 +600,7 @@ You can specify that the data be included like this:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
-  embed :ids, :include => true
+  embed :ids, include: true
 
   attributes :id, :title, :body
   has_many :comments
@@ -536,15 +630,55 @@ 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
+
 You can also specify a different root for the embedded objects than the key
 used to reference them:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
-  embed :ids, :include => true
+  embed :ids, include: true
 
   attributes :id, :title, :body
-  has_many :comments, :key => :comment_ids, :root => :comment_objects
+  has_many :comments, key: :comment_ids, root: :comment_objects
 end
 ```
 
@@ -569,10 +703,10 @@ objects:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
-  embed :ids, :include => true
+  embed :ids, include: true
 
   attributes :id, :title, :body
-  has_many :comments, :embed_key => :external_id
+  has_many :comments, key: :external_id
 end
 ```
 
@@ -600,6 +734,78 @@ 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.
 
+
+## Embedding Polymorphic Associations
+
+Because we need both the id and the type to be able to identify a polymorphic associated model, these are serialized in a slightly different format than common ones.
+
+When embedding entire objects:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title
+  has_many :attachments, polymorphic: true
+end
+```
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "attachments": [
+      {
+        "type": "image"
+        "image": {
+          "id": 3
+          "name": "logo"
+          "url": "http://images.com/logo.jpg"
+        }
+      },
+      {
+        "type": "video"
+        "video": {
+          "id": 12
+          "uid": "XCSSMDFWW"
+          "source": "youtube"
+        }
+      }
+    ]
+  }
+}
+```
+
+When embedding ids:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  embed :ids
+
+  attributes :id, :title
+  has_many :attachments, polymorphic: true
+end
+```
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "attachment_ids": [
+      {
+        "type": "image"
+        "id": 12
+      },
+      {
+        "type": "video"
+        "id": 3
+      }
+    ]
+  }
+}
+```
+
+
 ## Customizing Scope
 
 In a serializer, `current_user` is the current authorization scope which the controller
@@ -613,7 +819,7 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-The above example will also change the scope name from `current_user` to
+The above example will also change the scope from `current_user` to
 `current_admin`.
 
 Please note that, until now, `serialization_scope` doesn't accept a second
@@ -624,7 +830,7 @@ To be clear, it's not possible, yet, to do something like this:
 
 ```ruby
 class SomeController < ApplicationController
-  serialization_scope :current_admin, :except => [:index, :show]
+  serialization_scope :current_admin, except: [:index, :show]
 end
 ```
 
@@ -638,13 +844,13 @@ class CitiesController < ApplicationController
   def index
     @cities = City.all
 
-    render :json => @cities, :each_serializer => CitySerializer
+    render json: @cities, each_serializer: CitySerializer
   end
 
   def show
     @city = City.find(params[:id])
 
-    render :json => @city, :scope => current_admin, :scope_name => :current_admin
+    render json: @city, scope: current_admin
   end
 end
 ```
@@ -653,3 +859,97 @@ 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.
+
+## Testing
+
+In order to test a Serializer, you can just call `.new` on it, passing the object to serialize:
+
+### MiniTest
+
+```ruby
+class TestPostSerializer < Minitest::Test
+  def setup
+    @serializer = PostSerializer.new Post.new(id: 123, title: 'some title', body: 'some text')
+  end
+
+  def test_special_json_for_api
+    assert_equal '{"post":{"id":123,"title":"some title","body":"some text"}}', @serializer.to_json
+  end
+```
+
+### RSpec
+
+```ruby
+describe PostSerializer do
+  it "creates special JSON for the API" do
+    serializer = PostSerializer.new Post.new(id: 123, title: 'some title', body: 'some text')
+    expect(serializer.to_json).to eql('{"post":{"id":123,"title":"some title","body":"some text"}}')
+  end
+end
+```
+
+## Caching
+
+NOTE: This functionality was removed from AMS and it's in the TODO list.
+We need to re-think and re-design the caching strategy for the next
+version of AMS.
+
+To cache a serializer, call `cached` and define a `cache_key` method:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cached  # enables caching for this serializer
+
+  attributes :title, :body
+
+  def cache_key
+    [object, scope]
+  end
+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
+
+`ActiveModel::Serializers` is capable of producing complex JSON views/large object
+trees, and it may be tempting to design in this way so that your client can make
+fewer requests to get data and so that related querying can be optimized.
+However, keeping things simple in your serializers and controllers may
+significantly reduce complexity and maintenance over the long-term development
+of your application. Please consider reducing the complexity of the JSON views
+you provide via the serializers as you build out your application, so that
+controllers/services can be more easily reused without a lot of complexity
+later.
+
+## Performance
+
+As you develop your controllers or other code that utilizes serializers, try to
+avoid n+1 queries by ensuring that data loads in an optimal fashion, e.g. if you
+are using ActiveRecord, you might want to use query includes or joins as needed
+to make the data available that the serializer(s) need.