From 5b41e648c9375a0119af7702e4b76546adbe4618 Mon Sep 17 00:00:00 2001 From: Jo Liss Date: Tue, 17 Apr 2012 16:01:40 +0200 Subject: [PATCH] Wrap text to 80 columns --- README.markdown | 93 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 68 insertions(+), 25 deletions(-) diff --git a/README.markdown b/README.markdown index ad7060d6..379f7c92 100644 --- a/README.markdown +++ b/README.markdown @@ -2,15 +2,21 @@ # Purpose -The purpose of `ActiveModel::Serializers` is to provide an object to encapsulate serialization of `ActiveModel` objects, including `ActiveRecord` objects. +The purpose of `ActiveModel::Serializers` is to provide an object to +encapsulate serialization of `ActiveModel` objects, including `ActiveRecord` +objects. -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 content. +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 +content. -In short, **serializers replaces hash-driven development with object-oriented development.** +In short, **serializers replaces hash-driven development with object-oriented +development.** # Installing Serializers -For now, the easiest way to install `ActiveModel::Serializers` is to add this to your `Gemfile`: +For now, the easiest way to install `ActiveModel::Serializers` is to add this +to your `Gemfile`: ```ruby gem "active_model_serializers", :git => "git://github.com/josevalim/active_model_serializers.git" @@ -24,13 +30,16 @@ $ bundle install # Creating a Serializer -The easiest way to create a new serializer is to generate a new resource, which will generate a serializer at the same time: +The easiest way to create a new serializer is to generate a new resource, which +will generate a serializer at the same time: ``` $ 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`: +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`: ``` $ rails g serializer post @@ -38,11 +47,14 @@ $ rails g serializer post # ApplicationSerializer the global serializer -All new serializers descend from either ActiveModel::Serializer or from ApplicationSerializer if you create this file in `app/serializers`. This file is no longer required. +All new serializers descend from either ActiveModel::Serializer or from +ApplicationSerializer if you create this file in `app/serializers`. This file +is no longer required. # render :json -In your controllers, when you use `render :json`, Rails will now first search for a serializer for the object and use it if available. +In your controllers, when you use `render :json`, Rails will now first search +for a serializer for the object and use it if available. ```ruby class PostController < ApplicationController @@ -53,17 +65,22 @@ class PostController < ApplicationController end ``` -In this case, Rails will look for a serializer named `PostSerializer`, and if it exists, use it to serialize the `Post`. +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 note that any options passed to `render :json` will be passed to your serializer and available as `@options` inside. +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. ## 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`. +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`. # Attributes and Associations -Once you have a serializer, you can specify which attributes and associations you would like to include in the serialized form. +Once you have a serializer, you can specify which attributes and associations +you would like to include in the serialized form. ```ruby class PostSerializer < ApplicationSerializer @@ -74,9 +91,13 @@ end ## Attributes -For specified attributes, the 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. +For specified attributes, the 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. -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: +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: ```ruby class PostSerializer < ApplicationSerializer @@ -90,9 +111,15 @@ end ## Associations -For specified associations, the serializer will look up the association and then serialize each element of the association. For instance, a `has_many :comments` association will create a new `CommentSerializer` for each comment and use it to serialize the comment. +For specified associations, the serializer will look up the association and +then serialize each element of the association. For instance, a `has_many +:comments` association will create a new `CommentSerializer` for each comment +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. +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. ```ruby class PostSerializer < ApplicationSerializer @@ -106,9 +133,12 @@ class PostSerializer < ApplicationSerializer end ``` -In a serializer, `@scope` is the current authorization scope (usually `current_user`), which the controller gives to the serializer when you call `render :json` +In a serializer, `@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 use for a particular association. +As with attributes, you can also change the JSON key that the serializer should +use for a particular association. ```ruby class PostSerializer < ApplicationSerializer @@ -121,7 +151,8 @@ end ## Embedding Associations -By default, associations will be embedded inside the serialized object. So if you have a post, the outputted JSON will look like: +By default, associations will be embedded inside the serialized object. So if +you have a post, the outputted JSON will look like: ```json { @@ -136,7 +167,9 @@ By default, associations will be embedded inside the serialized object. So if yo } ``` -This is convenient for simple use-cases, but for more complex clients, it is better to supply an Array of IDs for the association. This makes your API more flexible from a performance standpoint and avoids wasteful duplication. +This is convenient for simple use-cases, but for more complex clients, it is +better to supply an Array of IDs for the association. This makes your API more +flexible from a performance standpoint and avoids wasteful duplication. To embed IDs instead of associations, simply use the `embed` class method: @@ -162,7 +195,11 @@ Now, any associations will be supplied as an Array of IDs: } ``` -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 information. It also ensures that associations that are shared between several objects (like tags), are only delivered once for the entire payload. +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 +information. It also ensures that associations that are shared between several +objects (like tags), are only delivered once for the entire payload. You can specify that the data be included like this: @@ -175,7 +212,8 @@ class PostSerializer < ApplicationSerializer end ``` -Assuming that the comments also `has_many :tags`, you will get a JSON like this: +Assuming that the comments also `has_many :tags`, you will get a JSON like +this: ```json { @@ -197,7 +235,8 @@ Assuming that the comments also `has_many :tags`, you will get a JSON like this: } ``` -You can also specify a different root for the embedded objects than the key used to reference them, such as like this: +You can also specify a different root for the embedded objects than the key +used to reference them, such as like this: ```ruby class PostSerializer < ApplicationSerializer @@ -224,6 +263,10 @@ This would generate JSON that would look like this: } ``` -**NOTE**: The `embed :ids` mechanism is primary useful for clients that process data in bulk and load it into a local store. For these clients, the ability to easily see all of the data per type, rather than having to recursively scan the data looking for information, is extremely useful. +**NOTE**: The `embed :ids` mechanism is primary useful for clients that process +data in bulk and load it into a local store. For these clients, the ability to +easily see all of the data per type, rather than having to recursively scan the +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. +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.