README.md in active_model_serializers-0.9.0 vs README.md in active_model_serializers-0.9.1
- old
+ new
@@ -1,14 +1,14 @@
-[](https://travis-ci.org/rails-api/active_model_serializers)
-[](https://codeclimate.com/github/rails-api/active_model_serializers)
+[](https://travis-ci.org/rails-api/active_model_serializers)
+[](https://codeclimate.com/github/rails-api/active_model_serializers)
# ActiveModel::Serializers
## Purpose
-`ActiveModel::Serializers` encapsulates the JSON serialization of objects.
-Objects that respond to read\_attribute\_for\_serialization
+`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
content.
@@ -92,10 +92,21 @@
```ruby
render json: @post, serializer: FancyPostSerializer
```
+### Use serialization outside of ActionController::Base
+
+When controller does not inherit from ActionController::Base,
+include Serialization module manually:
+
+```ruby
+class ApplicationController < ActionController::API
+ include ActionController::Serialization
+end
+```
+
## 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.
@@ -227,17 +238,29 @@
ActiveModel::Serializer.setup do |config|
config.key_format = :lower_camel
end
-class BlogLowerCamelSerializer < ActiveModel::Serializer
+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`.
@@ -279,11 +302,11 @@
Since this shadows any attribute named `object`, you can include them through `object.object`. For example:
```ruby
class VersionSerializer < ActiveModel::Serializer
- attribute :version_object, key: :object
+ attributes :version_object
def version_object
object.object
end
end
@@ -352,11 +375,11 @@
```
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:
```json
@@ -465,13 +488,10 @@
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.
-NOTE: polymorphic was removed because was only supported for has\_one
-associations and is in the TODO list of the project.
-
## Embedding Associations
By default, associations will be embedded inside the serialized object. So if
you have a post, the outputted JSON will look like:
@@ -514,19 +534,19 @@
"comment_ids": [ 1, 2, 3 ]
}
}
```
-You may also choose to embed the IDs by the association's name underneath an
-`embed_key` for the resource. For example, say we want to change `comment_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, embed_namespace: :links
+ has_many :comments, embed: :ids, key: :comments, embed_namespace: :links
end
```
The JSON will look like this:
@@ -613,11 +633,11 @@
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
+ embed :ids, include: true, embed_in_root_key: :linked
attributes: :id, :title, :body
has_many :comments, :tags
end
```
@@ -644,12 +664,12 @@
]
}
}
```
-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`
+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:
@@ -684,11 +704,11 @@
```ruby
class PostSerializer < ActiveModel::Serializer
embed :ids, include: true
attributes :id, :title, :body
- has_many :comments, embed_key: :external_id
+ has_many :comments, key: :external_id
end
```
This would generate JSON that would look like this:
@@ -711,9 +731,81 @@
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.
+
+
+## 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
provides to the serializer when you call `render :json`. By default, this is