Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Simple XML and JSON APIs for your Rails app
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
gemfiles
lib
test
.gitignore Add .rvmrc to .gitignore
.travis.yml
Appraisals
Gemfile
MIT-LICENSE
README.markdown Add Travis build
Rakefile
serialize_with_options.gemspec

README.markdown

SerializeWithOptions

Code Climate Build Status

This plugin is designed to make creating XML and JSON APIs for your Rails apps dead simple. We noticed a lot of repetition when creating API responses in our controllers. With this plugin, you can set the serialization options for a model with a simple DSL, rather than repeating them in every controller that includes it.

Example

Here is a simple example of SerializeWithOptions in action:

class User < ActiveRecord::Base
  has_many :posts

  serialize_with_options do
    methods   :post_count
    includes  :posts
    except    :email
  end

  serialize_with_options(:with_email) do
    methods   :post_count
    includes  :posts
  end

  def post_count
    self.posts.count
  end
end

class Post < ActiveRecord::Base
  has_many :comments
  belongs_to :user

  serialize_with_options do
    only      :title
    includes  :user, :comments
  end
end

class Comment < ActiveRecord::Base
  belongs_to :post
end

With these directives in place, we can call @post.to_xml (or @post.to_json) and it's as if we entered:

@post.to_xml(:include => { :user => { :methods => :post_count, :except => :email }, :comments => { } })

In our controller, we can just say:

def show
  @post = Post.find(params[:id])

  respond_to do |format|
    format.html
    format.xml { render :xml => @post }
    format.json { render :json => @post }
  end
end

All serialization options are enclosed in a serialize_with_options block. There are four options, lifted directly from ActiveRecord's serialization API: methods are the methods to add to the default attributes, only are the attributes to include, excluding all others, except are the attributes to leave out, and includes are the associated models.

If an included model has its own serialize_with_options block, its methods, only, and except will be respected. However, the included model's includes directive will be ignored (only one level of nesting is supported). If you need more than one level of nesting, you can use a hash to set your included models, rather than an array.

The serialize_with_options class method takes an optional argument for naming a configuration set (see the User model above). This is useful if you need to multiple serialization configuration sets. You can access these secondary configuration sets by passing the set name to the serialization method, e.g., @post.to_xml(:with_email).

Installation

Simply add "serialize_with_options" to your Gemfile:

gem "serialize_with_options"

And run "bundle install"


Copyright (c) 2009-2014 David Eisinger & Zachary Porter (Viget Labs), released under the MIT license.

Something went wrong with that request. Please try again.