isabella232 / ivy-serializers

JSON serialization for client-side apps.

ivy-serializers

JSON serialization for client-side apps, with multiple output formats. Ships with ActiveModel::Serializers and JSON-API 1.0 support out of the box.

If you're building a Rails project, take a look at ivy-serializers-rails instead.

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/my_serializer.rb:

class MySerializer < Ivy::Serializers::Serializer
  map Post do
    attributes :title
    has_many :comments
  end

  map Comment do
    attributes :body
    belongs_to :post
  end
end

NOTE: An id attribute is automatically defined for you. This is a consequence of supporting JSON-API, which requires all resources to have IDs.

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 :title
end

will read title from the post and write it into the hash under the :title key. 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.

Contributing

1. Fork it ( https://github.com/[my-github-username]/ivy-serializers/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request