serialize_with_options 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+test.db
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in serialize_with_options.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,80 @@
+SerializeWithOptions
+====================
+
+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][ser]: `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
+------------
+
+From your app root:
+
+    script/plugin install git://github.com/vigetlabs/serialize_with_options.git
+
+* * *
+
+Copyright (c) 2009-2010 David Eisinger ([Viget Labs][vgt]), released under the MIT license.
+
+[ser]: http://api.rubyonrails.org/classes/ActiveRecord/Serialization.html
+[vgt]: http://www.viget.com/

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler'
+require 'rake/testtask'
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*.rb'
+  test.verbose = true
+end

data/init.rb

@@ -0,0 +1 @@
+ActiveRecord::Base.extend(SerializeWithOptions)

data/lib/serialize_with_options/version.rb

@@ -0,0 +1,3 @@
+module SerializeWithOptions
+  VERSION = "0.1.0"
+end

data/lib/serialize_with_options.rb

@@ -0,0 +1,88 @@
+module SerializeWithOptions
+
+  def serialize_with_options(set = :default, &block)
+    configuration = read_inheritable_attribute(:configuration) || {}
+    options       = read_inheritable_attribute(:options) || {}
+
+    configuration[set] = Config.new.instance_eval(&block)
+
+    write_inheritable_attribute :configuration, configuration
+    write_inheritable_attribute :options, options
+
+    include InstanceMethods
+  end
+
+  def serialization_configuration(set)
+    configuration = read_inheritable_attribute(:configuration)
+    conf = if configuration
+      configuration[set] || configuration[:default]
+    end
+
+    conf.try(:dup) || { :methods => nil, :only => nil, :except => nil }
+  end
+
+  def serialization_options(set)
+    options = read_inheritable_attribute(:options)
+    options[set] ||= serialization_configuration(set).tap do |opts|
+      includes = opts.delete(:includes)
+
+      if includes
+        opts[:include] = includes.inject({}) do |hash, class_name|
+          if class_name.is_a? Hash
+            hash.merge(class_name)
+          else
+            begin
+              klass = class_name.to_s.classify.constantize
+              hash[class_name] = klass.serialization_configuration(set)
+              hash[class_name][:include] = nil if hash[class_name].delete(:includes)
+              hash
+            rescue NameError
+              hash.merge(class_name => { :include => nil })
+            end
+          end
+        end
+      end
+    end
+    write_inheritable_attribute :options, options
+    options[set]
+  end
+
+  class Config
+    undef_method :methods
+    Instructions = [:skip_instruct, :dasherize, :skip_types, :root_in_json].freeze
+
+    def initialize
+      @data = { :methods => nil, :only => nil, :except => nil }
+    end
+
+    def method_missing(method, *args)
+      @data[method] = Instructions.include?(method) ? args.first : args
+      @data
+    end
+  end
+
+  module InstanceMethods
+    def to_xml(opts = {})
+      set, opts = parse_serialization_options(opts)
+      super(self.class.serialization_options(set).deep_merge(opts))
+    end
+
+    def to_json(opts = {})
+      set, opts = parse_serialization_options(opts)
+      super(self.class.serialization_options(set).deep_merge(opts))
+    end
+
+    private
+
+    def parse_serialization_options(opts)
+      if opts.is_a? Symbol
+        set  = opts
+        opts = {}
+      else
+        set  = :default
+      end
+
+      [set, opts]
+    end
+  end
+end

data/serialize_with_options.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "serialize_with_options/version"
+
+Gem::Specification.new do |s|
+  s.name        = "serialize_with_options"
+  s.version     = SerializeWithOptions::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["David Eisinger"]
+  s.email       = ["david.eisinger@gmail.com"]
+  s.homepage    = "http://www.viget.com/extend/simple-apis-using-serializewithoptions"
+  s.summary     = %q{Simple XML and JSON APIs for your Rails app}
+  s.description = %q{Simple XML and JSON APIs for your Rails app}
+
+  s.rubyforge_project = "serialize_with_options"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "active_record", "~> 2.3"
+
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency "sqlite3"
+end

data/test/serialize_with_options_test.rb

@@ -0,0 +1,215 @@
+require 'test_helper'
+
+class User < ActiveRecord::Base
+  has_many :posts
+  has_many :blog_posts
+  has_many :check_ins
+  has_many :reviews, :as => :reviewable
+
+  serialize_with_options do
+    methods   :post_count
+    includes  :posts
+    except    :email
+  end
+
+  serialize_with_options(:with_email) do
+    methods   :post_count
+    includes  :posts
+  end
+
+  serialize_with_options(:with_comments) do
+    includes  :posts => { :include => :comments }
+  end
+
+  serialize_with_options(:with_check_ins) do
+    includes :check_ins
+    dasherize false
+    skip_types true
+  end
+
+  serialize_with_options(:with_reviews) do
+    includes :reviews
+  end
+
+  def post_count
+    self.posts.count
+  end
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :user
+  has_many :comments
+  has_many :reviews, :as => :reviewable
+
+  serialize_with_options do
+    only :title
+    includes :user, :comments
+  end
+
+  serialize_with_options(:with_email) do
+    includes :user, :comments
+  end
+end
+
+class BlogPost < Post
+  serialize_with_options(:with_email) do
+    includes :user
+  end
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+
+class CheckIn < ActiveRecord::Base
+  belongs_to :user
+
+  serialize_with_options do
+    only :code_name
+    includes :user
+  end
+end
+
+class Review < ActiveRecord::Base
+  belongs_to :reviewable, :polymorphic => true
+
+  serialize_with_options do
+    includes :reviewable
+  end
+end
+
+class SerializeWithOptionsTest < Test::Unit::TestCase
+  def self.should_serialize_with_options
+    should "include active_record attributes" do
+      assert_equal @user.name, @user_hash["name"]
+    end
+
+    should "include specified methods" do
+      assert_equal @user.post_count, @user_hash["post_count"]
+    end
+
+    should "exclude specified attributes" do
+      assert_equal nil, @user_hash["email"]
+    end
+
+    should "exclude attributes not in :only list" do
+      assert_equal nil, @post_hash["content"]
+    end
+
+    should "include specified associations" do
+      assert_equal @post.title, @user_hash["posts"].first["title"]
+    end
+
+    should "be identical in inherited model" do
+      assert_equal @post_hash["title"], @blog_post_hash["title"]
+    end
+
+    should "include specified methods on associations" do
+      assert_equal @user.post_count, @post_hash["user"]["post_count"]
+    end
+
+    should "exclude specified methods on associations" do
+      assert_equal nil,  @post_hash["user"]["email"]
+    end
+
+    should "not include associations of associations" do
+      assert_equal nil, @user_hash["posts"].first["comments"]
+    end
+
+    should "include association without serialization options properly" do
+      assert_equal @comment.content, @post_hash["comments"].first["content"]
+    end
+
+    should "override sets on inherited models" do
+      assert_equal nil, @blog_post_hash["comments"].first
+    end
+  end
+
+  context "An instance of a class with serialization options" do
+    setup do
+      @user = User.create(:name => "John User", :email => "john@example.com")
+      @post = @user.posts.create(:title => "Hello World!", :content => "Welcome to my blog.")
+      @blog_post = @user.blog_posts.create(:title => "Hello World!", :content => "Welcome to my blog.")
+      @comment = @post.comments.create(:content => "Great blog!")
+    end
+
+    context "being converted to XML" do
+      setup do
+        @user_hash = Hash.from_xml(@user.to_xml)["user"]
+        @post_hash = Hash.from_xml(@post.to_xml)["post"]
+        @blog_post_hash = Hash.from_xml(@blog_post.to_xml)["blog_post"]
+      end
+
+      should_serialize_with_options
+    end
+
+
+    should "accept additional properties w/o overwriting defaults" do
+      xml = @post.to_xml(:include => { :user => { :except => nil } })
+      post_hash = Hash.from_xml(xml)["post"]
+
+      assert_equal @user.email,       post_hash["user"]["email"]
+      assert_equal @user.post_count,  post_hash["user"]["post_count"]
+    end
+
+    should "accept a hash for includes directive" do
+      user_hash = Hash.from_xml(@user.to_xml(:with_comments))["user"]
+      assert_equal @comment.content, user_hash["posts"].first["comments"].first["content"]
+    end
+
+    context "with a secondary configuration" do
+      should "use it" do
+        user_hash = Hash.from_xml(@user.to_xml(:with_email))["user"]
+        assert_equal @user.email, user_hash["email"]
+      end
+
+      should "pass it through to included models" do
+        post_hash = Hash.from_xml(@post.to_xml(:with_email))["post"]
+        assert_equal @user.email, post_hash["user"]["email"]
+      end
+    end
+
+    context "with a polymorphic relationship" do
+      setup do
+        @review = Review.create(:reviewable => @user, :content => "troll")
+      end
+
+      should "include the associated object" do
+        user_hash = Hash.from_xml(@user.to_xml(:with_reviews))
+        assert_equal @review.content, user_hash["user"]["reviews"].first["content"]
+      end
+
+      should "serialize the associated object properly" do
+        review_hash = Hash.from_xml(@review.to_xml)
+        assert_equal @user.email, review_hash["review"]["reviewable"]["email"]
+      end
+    end
+
+    context "being converted to JSON" do
+      setup do
+        @user_hash = JSON.parse(@user.to_json)
+        @post_hash = JSON.parse(@post.to_json)
+        @blog_post_hash = JSON.parse(@blog_post.to_json)
+      end
+
+      should_serialize_with_options
+    end
+
+    context "serializing associated models" do
+      setup do
+        @user = User.create(:name => "John User", :email => "john@example.com")
+        @check_in = @user.check_ins.create(:code_name => "Hello World")
+      end
+
+      should "find associations with multi-word names" do
+        user_hash = JSON.parse(@user.to_json(:with_check_ins))
+        assert_equal @check_in.code_name, user_hash['check_ins'].first['code_name']
+      end
+
+      should "respect xml formatting options" do
+        assert !@user.to_xml(:with_check_ins).include?('check-ins')
+        assert !@user.to_xml(:with_check_ins).include?('type=')
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,45 @@
+$:.unshift(File.dirname(__FILE__) + '/..')
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'rubygems'
+require 'active_record'
+require 'test/unit'
+require 'shoulda'
+require 'json'
+require 'serialize_with_options'
+require 'init'
+
+ActiveRecord::Base.establish_connection(:adapter => 'sqlite3', :database => ':memory:')
+
+[:users, :posts, :comments, :check_ins, :reviews].each do |table|
+  ActiveRecord::Base.connection.drop_table table rescue nil
+end
+
+ActiveRecord::Base.connection.create_table :users do |t|
+  t.string :name
+  t.string :email
+end
+
+ActiveRecord::Base.connection.create_table :posts do |t|
+  t.string :title
+  t.text :content
+  t.integer :user_id
+  t.string :type
+end
+
+ActiveRecord::Base.connection.create_table :comments do |t|
+  t.text :content
+  t.integer :post_id
+end
+
+ActiveRecord::Base.connection.create_table :check_ins do |t|
+  t.integer :user_id
+  t.string :code_name
+end
+
+ActiveRecord::Base.connection.create_table :reviews do |t|
+  t.string :content
+  t.integer :reviewable_id
+  t.string :reviewable_type
+end
+

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: serialize_with_options
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- David Eisinger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-10 00:00:00.000000000 -04:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: active_record
+  requirement: &2153256800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2153256800
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: &2153256380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2153256380
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &2153255920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2153255920
+description: Simple XML and JSON APIs for your Rails app
+email:
+- david.eisinger@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README.markdown
+- Rakefile
+- init.rb
+- lib/serialize_with_options.rb
+- lib/serialize_with_options/version.rb
+- serialize_with_options.gemspec
+- test/serialize_with_options_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://www.viget.com/extend/simple-apis-using-serializewithoptions
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: serialize_with_options
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Simple XML and JSON APIs for your Rails app
+test_files:
+- test/serialize_with_options_test.rb
+- test/test_helper.rb