From 4900432ac29f210ddda3ee9cdd01ad7cdd389adc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Mendon=C3=A7a=20Fran=C3=A7a?= Date: Thu, 1 Dec 2011 13:39:42 -0200 Subject: [PATCH] Now @josevalim can stop to fight with textile --- README.textile | 84 +++++++++++++++++++++++++------------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/README.textile b/README.textile index d60af5b16..8cd1cd3c6 100644 --- a/README.textile +++ b/README.textile @@ -35,7 +35,7 @@ h3. The Most Basic Serializer A basic serializer is a simple Ruby object named after the model class it is serializing. -

+
 class PostSerializer
   def initialize(post, scope)
     @post, @scope = post, scope
@@ -45,7 +45,7 @@ class PostSerializer
     { post: { title: @post.name, body: @post.body } }
   end
 end
-

+
A serializer is initialized with two parameters: the model object it should serialize and an authorization scope. By default, the authorization scope is the current user (+current_user+) but you can use a different object if you want. The serializer also @@ -53,14 +53,14 @@ implements an +as_json+ method, which returns a Hash that will be sent to the JS Rails will transparently use your serializer when you use +render :json+ in your controller. -

+
 class PostsController < ApplicationController
   def show
     @post = Post.find(params[:id])
     render json: @post
   end
 end
-

+
Because +respond_with+ uses +render :json+ under the hood for JSON requests, Rails will automatically use your serializer when you use +respond_with+ as well. @@ -70,7 +70,7 @@ h4. +serializable_hash+ In general, you will want to implement +serializable_hash+ and +as_json+ to allow serializers to embed associated content directly. The easiest way to implement these two methods is to have +as_json+ call +serializable_hash+ and insert the root. -

+
 class PostSerializer
   def initialize(post, scope)
     @post, @scope = post, scope
@@ -84,14 +84,14 @@ class PostSerializer
     { post: serializable_hash }
   end
 end
-

+
h4. Authorization Let's update our serializer to include the email address of the author of the post, but only if the current user has superuser access. -

+
 class PostSerializer
   def initialize(post, scope)
     @post, @scope = post, scope
@@ -120,14 +120,14 @@ private
     @scope.superuser?
   end
 end
-

+
h4. Testing One benefit of encapsulating our objects this way is that it becomes extremely straight-forward to test the serialization logic in isolation. -

+
 require "ostruct"
 
 class PostSerializerTest < ActiveSupport::TestCase
@@ -157,7 +157,7 @@ class PostSerializerTest < ActiveSupport::TestCase
     assert_empty hash
   end
 end
-

+
It's important to note that serializer objects define a clear interface specifically for serializing an existing object. In this case, the serializer expects to receive a post object with +name+, +body+ and +email+ attributes and an authorization @@ -168,7 +168,7 @@ the serializer doesn't need to concern itself with how the authorization scope d whether it is set. In general, you should document these requirements in your serializer files and programatically via tests. The documentation library +YARD+ provides excellent tools for describing this kind of requirement: -

+
 class PostSerializer
   # @param [~body, ~title, ~email] post the post to serialize
   # @param [~super] scope the authorization scope for this serializer
@@ -178,7 +178,7 @@ class PostSerializer
 
   # ...
 end
-

+
h3. Attribute Sugar @@ -189,7 +189,7 @@ For example, you will sometimes want to simply include a number of existing attr JSON. In the above example, the +title+ and +body+ attributes were always included in the JSON. Let's see how to use +ActiveModel::Serializer+ to simplify our post serializer. -

+
 class PostSerializer < ActiveModel::Serializer
   attributes :title, :body
 
@@ -212,7 +212,7 @@ private
     @scope.superuser?
   end
 end
-

+
First, we specified the list of included attributes at the top of the class. This will create an instance method called +attributes+ that extracts those attributes from the post model. @@ -223,7 +223,7 @@ Next, we use the attributes methood in our +serializable_hash+ method, which all earlier. We could also eliminate the +as_json+ method, as +ActiveModel::Serializer+ provides a default +as_json+ method for us that calls our +serializable_hash+ method and inserts a root. But we can go a step further! -

+
 class PostSerializer < ActiveModel::Serializer
   attributes :title, :body
 
@@ -238,7 +238,7 @@ private
     @scope.superuser?
   end
 end
-

+
The superclass provides a default +initialize+ method as well as a default +serializable_hash+ method, which uses +attributes+. We can call +super+ to get the hash based on the attributes we declared, and then add in any additional @@ -251,7 +251,7 @@ h3. Associations In most JSON APIs, you will want to include associated objects with your serialized object. In this case, let's include the comments with the current post. -

+
 class PostSerializer < ActiveModel::Serializer
   attributes :title, :body
   has_many :comments
@@ -267,11 +267,11 @@ private
     @scope.superuser?
   end
 end
-

+
The default +serializable_hash+ method will include the comments as embedded objects inside the post. -

+
 {
   post: {
     title: "Hello Blog!",
@@ -284,14 +284,14 @@ The default +serializable_hash+ method will include the comments as embedded obj
     ]
   }
 }
-

+
Rails uses the same logic to generate embedded serializations as it does when you use +render :json+. In this case, because you didn't define a +CommentSerializer+, Rails used the default +as_json+ on your comment object. If you define a serializer, Rails will automatically instantiate it with the existing authorization scope. -

+
 class CommentSerializer
   def initialize(comment, scope)
     @comment, @scope = comment, scope
@@ -305,11 +305,11 @@ class CommentSerializer
     { comment: serializable_hash }
   end
 end
-

+
If we define the above comment serializer, the outputted JSON will change to: -

+
 {
   post: {
     title: "Hello Blog!",
@@ -317,14 +317,14 @@ If we define the above comment serializer, the outputted JSON will change to:
     comments: [{ title: "Awesome" }]
   }
 }
-

+
Let's imagine that our comment system allows an administrator to kill a comment, and we only want to allow users to see the comments they're entitled to see. By default, +has_many :comments+ will simply use the +comments+ accessor on the post object. We can override the +comments+ accessor to limit the comments used to just the comments we want to allow for the current user. -

+
 class PostSerializer < ActiveModel::Serializer
   attributes :title. :body
   has_many :comments
@@ -344,7 +344,7 @@ private
     @scope.superuser?
   end
 end
-

+
+ActiveModel::Serializer+ will still embed the comments, but this time it will use just the comments for the current user. @@ -359,7 +359,7 @@ build up the hash manually. For example, let's say our front-end expects the posts and comments in the following format: -

+
 {
   post: {
     id: 1
@@ -380,11 +380,11 @@ For example, let's say our front-end expects the posts and comments in the follo
     }
   ]
 }
-

+
We could achieve this with a custom +as_json+ method. We will also need to define a serializer for comments. -

+
 class CommentSerializer < ActiveModel::Serializer
   attributes :id, :title, :body
 
@@ -420,7 +420,7 @@ private
     @scope.superuser?
   end
 end
-

+
Here, we used two convenience methods: +associations+ and +association_ids+. The first, +associations+, creates a hash of all of the define associations, using their defined @@ -442,7 +442,7 @@ For instance, we might want to provide the full comment when it is requested dir but only its title when requested as part of the post. To achieve this, you can define a serializer for associated objects nested inside the main serializer. -

+
 class PostSerializer < ActiveModel::Serializer
   class CommentSerializer < ActiveModel::Serializer
     attributes :id, :title
@@ -451,7 +451,7 @@ class PostSerializer < ActiveModel::Serializer
   # same as before
   # ...
 end
-

+
In other words, if a +PostSerializer+ is trying to serialize comments, it will first look for +PostSerializer::CommentSerializer+ before falling back to +CommentSerializer+ @@ -468,11 +468,11 @@ its +current_user+ method and pass that along to the serializer's initializer. If you want to change that behavior, simply use the +serialization_scope+ class method. -

+
 class PostsController < ApplicationController
   serialization_scope :current_app
 end
-

+
You can also implement an instance method called (no surprise) +serialization_scope+, which allows you to define a dynamic authorization scope based on the current request. @@ -489,19 +489,19 @@ outside a request. For instance, if you want to generate the JSON representation of a post for a user outside of a request: -

+
 user = get_user # some logic to get the user in question
 PostSerializer.new(post, user).to_json # reliably generate JSON output
-

+
If you want to generate JSON for an anonymous user, you should be able to use whatever technique you use in your application to generate anonymous users outside of a request. Typically, that means creating a new user and not saving it to the database: -

+
 user = User.new # create a new anonymous user
 PostSerializer.new(post, user).to_json
-

+
In general, the better you encapsulate your authorization logic, the more easily you will be able to use the serializer outside of the context of a request. For instance, @@ -519,7 +519,7 @@ as the root). For example, an Array of post objects would serialize as: -

+
 {
   posts: [
     {
@@ -531,12 +531,12 @@ For example, an Array of post objects would serialize as:
     }
   ]
 }
-

+
If you want to change the behavior of serialized Arrays, you need to create a custom Array serializer. -

+
 class ArraySerializer < ActiveModel::ArraySerializer
   def serializable_array
     serializers.map do |serializer|
@@ -550,7 +550,7 @@ class ArraySerializer < ActiveModel::ArraySerializer
     hash
   end
 end
-

+
When generating embedded associations using the +associations+ helper inside a regular serializer, it will create a new ArraySerializer with the