diff --git a/README.markdown b/README.markdown index b2083e86..8d990075 100644 --- a/README.markdown +++ b/README.markdown @@ -88,6 +88,86 @@ To specify a custom serializer for an object, there are 2 options: 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 = "items" + 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 diff --git a/lib/active_model/serializer.rb b/lib/active_model/serializer.rb index 6868369a..5faf3958 100644 --- a/lib/active_model/serializer.rb +++ b/lib/active_model/serializer.rb @@ -32,7 +32,7 @@ module ActiveModel # It serializes an Array, checking if each element that implements # the +active_model_serializer+ method. # - # To disable serialization of root elements, in an initializer: + # To disable serialization of root elements: # # ActiveModel::ArraySerializer.root = false #