Ivy::Serializers
JSON serialization for client-side apps, with multiple output formats. Ships with ActiveModel::Serializers and JSON-API RC3 support out of the box.
Installation
Add this line to your application's Gemfile:
gem 'ivy-serializers'
And then execute:
bundle
Or install it yourself:
gem install ivy-serializers
Usage
Defining a Serializer
Assuming we have Post
and Comment
models:
class Post < ActiveRecord::Base
has_many :comments
end
class Comment < ActiveRecord::Base
belongs_to :post
end
Define a serializer in app/serializers/serializer.rb
:
class Serializer < Ivy::Serializers::Serializer
map Post do
attributes :id, :title
has_many :comments
end
map Comment do
attributes :id, :body
belongs_to :post
end
end
Then set up your controllers to use the serializer:
class ApplicationController < ActionController::Base
self.serializer = Serializer
end
Note that you're not limited to a single serializer. If you have multiple
serialization formats, such as one for admin and one for public-facing, you can
define alternate serializers in app/serializers
and use them as well.
Sideloading
The #belongs_to
and #has_many
methods support an optional :embed_in_root
option, which will load the associated record into the root of the payload. For
instance, if we wanted the list of comments to be included when fetching
a post, we could define the has_many
relationship like so:
map Post do
has_many :comments, :embed_in_root => true
end
The same thing also works with belongs_to
, so if we wanted to ensure the post
was included when fetching a comment:
map Comment do
belongs_to :post, :embed_in_root => true
end
Polymorphic Associations
There is also support for polymorphic associations. To use it, pass the
:polymorphic => true
option to the #belongs_to
or #has_many
methods:
map Post do
has_many :replies, :polymorphic => true
end
map Comment do
belongs_to :commentable, :polymorphic => true
end
Customizing Attributes
By default, attributes are mapped directly to methods on the record being serialized. So defining:
map Post do
attributes :id, :title
end
will read id
and title
from the post and write it into the hash under the
:id
and :title
keys. If you want to customize the value, you can use the
#attribute
method instead, and pass it a block:
map Post do
attribute(:title) { |post| post.headline }
end
In the above example, we read the headline
attribute from the post and write
it into the payload under the :title
key.
Alternate Output Formats
By default the ActiveModel::Serializers output format is used. If you'd rather
use JSON-API (or a custom format), you can do so by setting
serialization_format
in your controller. For instance, to use JSON-API:
class ApplicationController < ActionController::Base
self.serialization_format = Ivy::Serializers::Formats::JSONAPI
end
Contributing
- Fork it ( https://github.com/[my-github-username]/ivy-serializers/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request