Conglomerate

A library to serialize Ruby objects into collection+json.

This library focuses just on converting Ruby objects into Collection+JSON. It aims to have the simplest format possible when constructing serializers specific to Collection+JSON. It also tries to provide all common Collection+JSON extensions to make it easy to create your API.

Installation

Add this line to your application's Gemfile:

gem 'conglomerate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install conglomerate

Usage

# Step 1: Create a serializer
class TeamSerializer
  include Conglomerate::RootBuilder.serializer

  collection do
    href { teams_url }

    item "Team" do |item|
      href { team_url(item.id) }

      datum :id
      datum :name
      datum :event_ids

      link :events, :href => Proc.new { event_url(item.event_ids.join(",")) }
    end

    link :root, :href => Proc.new { root_url }

    query :search, :href => Proc.new { search_items_url } do
      datum :id
    end

    template do
      datum :name
    end
  end
end

# Step 2: Serialize any object

class TeamsController < ApplicationController
  def index
    teams = [
      OpenStruct.new(:id => 1, :name => "Team 01", :event_ids => [1,2,3]),
      OpenStruct.new(:id => 2, :name => "Team 02", :event_ids => [4,5,6]),
    ]
    render :json => TeamSerializer.new(teams, :context => self).serialize
  end
end

# Note, context is optional. It allows you to call helper methods such as url helpers easily inside the serializer.

{
  "collection": {
    "href": "http://example.com/teams",
    "items": [
      {
        "href": "http://example.com/teams/1",
        "data": [
          {"name": "id", "value": 1},
          {"name": "name", "value": "Team 01"},
          {"name": "event_ids", "value": [1,2,3]}
        ],
        "links": [
          {"rel": "events", "href": "http://example.com/events/1,2,3"}
        ]
      },
      {
        "href": "http://example.com/teams/2",
        "data": [
          {"name": "id", "value": 2},
          {"name": "name", "value": "Team 2"},
          {"name": "event_ids", "value": [4,5,6]}
        ],
        "links": [
          {"rel": "events", "href": "http://example.com/events/4,5,6"}
        ]
      }
    ],
    "links": [
      {"rel": "root", "href": "http://example.com"}
    ],
    "queries": [
      {
        "rel": "search",
        "href": "http://example.com/teams/search",
        "data": [
          {"name": "id", "value": ""}
        ]
      }
    ],
    "template": {
      "data": [
        {"name": "name", "value": ""}
      ]
    }
  }
}

Collection+JSON Extensions

Command Templates Data Properties

Contributing

1. Fork it ( http://github.com/teamsnap/conglomerate/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 new Pull Request