From bf2fa2d31c2d13c9509606c1329a14ff23fc6714 Mon Sep 17 00:00:00 2001 From: Tee Parham Date: Sat, 21 Jul 2012 15:25:08 -0700 Subject: [PATCH 1/4] add docs for custom serializers --- README.markdown | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.markdown b/README.markdown index 5fab7d2d..b2083e86 100644 --- a/README.markdown +++ b/README.markdown @@ -70,6 +70,24 @@ This also works with `render_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 +``` + ## Getting the old version If you find that your project is already relying on the old rails to_json From 53da0b12fdf34a15fdd8997368608c1aab481052 Mon Sep 17 00:00:00 2001 From: Tee Parham Date: Sat, 21 Jul 2012 15:25:41 -0700 Subject: [PATCH 2/4] add docs for serializing arrays --- README.markdown | 80 ++++++++++++++++++++++++++++++++++ lib/active_model/serializer.rb | 2 +- 2 files changed, 81 insertions(+), 1 deletion(-) 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 # From f8263153b6a9c6f2a92c71e5061a54f42c63bce3 Mon Sep 17 00:00:00 2001 From: Tee Parham Date: Mon, 23 Jul 2012 12:49:02 -0600 Subject: [PATCH 3/4] cleanup markdown in docs --- README.markdown | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/README.markdown b/README.markdown index 8d990075..ec5a2bab 100644 --- a/README.markdown +++ b/README.markdown @@ -72,20 +72,20 @@ 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: +#### 1. Specify the serializer in your model: ```ruby - class Post < ActiveRecord::Base - def active_model_serializer - FancyPostSerializer - end +class Post < ActiveRecord::Base + def active_model_serializer + FancyPostSerializer end +end ``` -2. Specify the serializer when you render the object: +#### 2. Specify the serializer when you render the object: ```ruby - render :json => @post, :serializer => FancyPostSerializer +render :json => @post, :serializer => FancyPostSerializer ``` ## Arrays @@ -123,33 +123,33 @@ By default, the root element is the name of the controller. For example, PostsCo 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 more concise json. To disable the root element for arrays, you have 3 options: -1. Disable root globally for in ArraySerializer. In an initializer: +#### 1. Disable root globally for in ArraySerializer. In an initializer: ```ruby - ActiveModel::ArraySerializer.root = false +ActiveModel::ArraySerializer.root = false ``` -2. Disable root per render call in your controller: +#### 2. Disable root per render call in your controller: ```ruby - render :json => @posts, :root => false +render :json => @posts, :root => false ``` -3. Create a custom ArraySerializer and render arrays with it: +#### 3. Create a custom ArraySerializer and render arrays with it: ```ruby - class CustomArraySerializer < ActiveModel::ArraySerializer - self.root = "items" - end +class CustomArraySerializer < ActiveModel::ArraySerializer + self.root = "items" +end - # controller: - render :json => @posts, :serializer => CustomArraySerializer +# controller: +render :json => @posts, :serializer => CustomArraySerializer ``` Disabling the root element of the array with any of the above 3 methods @@ -165,7 +165,7 @@ 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 ``` ## Getting the old version From 3ecf22a2490f111cccbf025d5b1264d2f9f58736 Mon Sep 17 00:00:00 2001 From: Tee Parham Date: Mon, 23 Jul 2012 12:55:47 -0600 Subject: [PATCH 4/4] more README markdown cleanup --- README.markdown | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.markdown b/README.markdown index ec5a2bab..371374ed 100644 --- a/README.markdown +++ b/README.markdown @@ -91,8 +91,8 @@ 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. +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 @@ -112,14 +112,14 @@ Given the example above, the index action will return ```json { "posts": - [ - { "title": "Post 1", "body": "Hello!" }, - { "title": "Post 2", "body": "Goodbye!" } - ] + [ + { "title": "Post 1", "body": "Hello!" }, + { "title": "Post 2", "body": "Goodbye!" } + ] } ``` -By default, the root element is the name of the controller. For example, PostsController +By default, the root element is the name of the controller. For example, `PostsController` generates a root element "posts". To change it: ```ruby @@ -129,7 +129,7 @@ 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: +#### 1. Disable root globally for in `ArraySerializer`. In an initializer: ```ruby ActiveModel::ArraySerializer.root = false @@ -141,7 +141,7 @@ ActiveModel::ArraySerializer.root = false render :json => @posts, :root => false ``` -#### 3. Create a custom ArraySerializer and render arrays with it: +#### 3. Create a custom `ArraySerializer` and render arrays with it: ```ruby class CustomArraySerializer < ActiveModel::ArraySerializer