README.md in active_model_serializers-0.10.0.rc2 vs README.md in active_model_serializers-0.10.0.rc3
- old
+ new
@@ -1,16 +1,20 @@
-# ActiveModel::Serializers
+# ActiveModel::Serializer
[](https://travis-ci.org/rails-api/active_model_serializers)
+<a href="https://codeclimate.com/github/rails-api/active_model_serializers"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/gpa.svg" /></a>
+<a href="https://codeclimate.com/github/rails-api/active_model_serializers/coverage"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/coverage.svg" /></a>
-ActiveModel::Serializers brings convention over configuration to your JSON generation.
+_Windows Build Status -_ [](https://ci.appveyor.com/project/joaomdmoura/active-model-serializers/branch/master)
+ActiveModel::Serializer brings convention over configuration to your JSON generation.
+
AMS does this through two components: **serializers** and **adapters**.
Serializers describe _which_ attributes and relationships should be serialized.
Adapters describe _how_ attributes and relationships should be serialized.
-By default AMS will use the **Json Adapter**. But we strongly advise you to use JsonApi Adapter that follows 1.0 of the format specified in [jsonapi.org/format](http://jsonapi.org/format).
+By default AMS will use the **Flatten Json Adapter**. But we strongly advise you to use **JsonApi Adapter** that follows 1.0 of the format specified in [jsonapi.org/format](http://jsonapi.org/format).
Check how to change the adapter in the sections bellow.
# RELEASE CANDIDATE, PLEASE READ
This is the master branch of AMS. It will become the `0.10.0` release when it's
@@ -21,33 +25,29 @@
architecture. We'd love your help. [Learn how you can help here.](https://github.com/rails-api/active_model_serializers/blob/master/CONTRIBUTING.md)
## Example
Given two models, a `Post(title: string, body: text)` and a
-`Comment(name:string, body:text, post_id:integer)`, you will have two
+`Comment(name: string, body: text, post_id: integer)`, you will have two
serializers:
```ruby
class PostSerializer < ActiveModel::Serializer
cache key: 'posts', expires_in: 3.hours
attributes :title, :body
has_many :comments
-
- url :post
end
```
and
```ruby
class CommentSerializer < ActiveModel::Serializer
attributes :name, :body
belongs_to :post
-
- url [:post, :comment]
end
```
Generally speaking, you as a user of AMS will write (or generate) these
serializer classes. If you want to use a different adapter, such as a JsonApi, you can
@@ -64,10 +64,16 @@
```
You won't need to implement an adapter unless you wish to use a new format or
media type with AMS.
+If you want to have a root key on your responses you should use the Json adapter, instead of the default FlattenJson:
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json
+```
+
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 < ActiveModel::Serializer
attributes :id, :body
@@ -110,11 +116,11 @@
# Use the default `ArraySerializer`, which will use `each_serializer` to
# serialize each element
render json: @posts, each_serializer: PostPreviewSerializer
# Or, you can explicitly provide the collection serializer as well
-render json: @posts, serializer: PaginatedSerializer, each_serializer: PostPreviewSerializer
+render json: @posts, serializer: CollectionSerializer, each_serializer: PostPreviewSerializer
```
### Meta
If you want a `meta` attribute in your response, specify it in the `render`
@@ -128,20 +134,27 @@
```ruby
render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
```
-`meta` will only be included in your response if there's a root. For instance,
-it won't be included in array responses.
+`meta` will only be included in your response if you are using an Adapter that supports `root`, as JsonAPI and Json adapters, the default adapter (FlattenJson) doesn't have `root`.
-### Root key
+### Using a serializer without `render`
-If you want to define a custom root for your response, specify it in the `render`
-call:
+At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModel::SerializableResource` with
+the resource you want to be serialized and call `.serializable_hash`.
```ruby
-render json: @post, root: "articles"
+def create
+ @message = current_user.messages.create!(message_params)
+ MessageCreationWorker.perform(serialized_message)
+ head 204
+end
+
+def serialized_message
+ ActiveModel::SerializableResource.new(@message).serializable_hash
+end
```
### Overriding association methods
If you want to override any association, you can use:
@@ -174,21 +187,31 @@
end
```
### Built in Adapters
+#### FlattenJSON
+
+It's the default adapter, it generates a json response without a root key.
+Doesn't follow any specifc convention.
+
+#### JSON
+
+It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly with the objects being serialized.
+Doesn't follow any specifc convention.
+
#### JSONAPI
-This adapter follows RC4 of the format specified in
+This adapter follows 1.0 of the format specified in
[jsonapi.org/format](http://jsonapi.org/format). It will include the associated
resources in the `"included"` member when the resource names are included in the
-`include` option.
+`include` option. Including nested associated resources is also supported.
```ruby
- render @posts, include: ['authors', 'comments']
+ render @posts, include: ['author', 'comments', 'comments.author']
# or
- render @posts, include: 'authors,comments'
+ render @posts, include: 'author,comments,comments.author'
```
## Installation
Add this line to your application's Gemfile:
@@ -227,42 +250,47 @@
class PostSerializer < ActiveModel::Serializer
attributes :title, :body
has_many :comments
has_one :author
-
- url :post
end
```
and
```ruby
class CommentSerializer < ActiveModel::Serializer
attributes :name, :body
belongs_to :post_id
-
- url [:post, :comment]
end
```
The attribute names are a **whitelist** of attributes to be serialized.
The `has_many`, `has_one`, and `belongs_to` declarations describe relationships between
-resources. By default, when you serialize a `Post`, you will get its `Comment`s
+resources. By default, when you serialize a `Post`, you will get its `Comments`
as well.
You may also use the `:serializer` option to specify a custom serializer class, for example:
```ruby
has_many :comments, serializer: CommentPreviewSerializer
```
-The `url` declaration describes which named routes to use while generating URLs
-for your JSON. Not every adapter will require URLs.
+And you can change the JSON key that the serializer should use for a particular association:
+```ruby
+ has_many :comments, key: :reviews
+```
+
+## Pagination
+
+Pagination links will be included in your response automatically as long as the resource is paginated using [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate) and if you are using a ```JSON-API``` adapter.
+
+Although the others adapters does not have this feature, it is possible to implement pagination links to `JSON` adapter. For more information about it, please see in our docs [How to add pagination links](https://github.com/rails-api/active_model_serializers/blob/master/docs/howto/add_pagination_links.md)
+
## Caching
To cache a serializer, call ```cache``` and pass its options.
The options are the same options of ```ActiveSupport::Cache::Store```, plus
a ```key``` option that will be the prefix of the object cache
@@ -270,11 +298,11 @@
The cache support is optimized to use the cached object in multiple request. An object cached on a ```show``` request will be reused at the ```index```. If there is a relationship with another cached serializer it will also be created and reused automatically.
**[NOTE] Every object is individually cached.**
-**[NOTE] The cache is automatically expired after update an object but it's not deleted.**
+**[NOTE] The cache is automatically expired after an object is updated, but it's not deleted.**
```ruby
cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
```
@@ -284,12 +312,10 @@
class PostSerializer < ActiveModel::Serializer
cache key: 'post', expires_in: 3.hours
attributes :title, :body
has_many :comments
-
- url :post
end
```
On this example every ```Post``` object will be cached with
the key ```"post/#{post.id}-#{post.updated_at}"```. You can use this key to expire it as you want,
@@ -309,11 +335,9 @@
class PostSerializer < ActiveModel::Serializer
cache key: 'post', expires_in: 3.hours, only: [:title]
attributes :title, :body
has_many :comments
-
- url :post
end
```
## Getting Help