No commit activity in last 3 years
No release in over 3 years
Resource Inclusion allows one to specify once per controller associated resources to be included when a resource is serialized.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

>= 3.0.1
 Project Readme

Resource Inclusion¶ ↑

Resource Inclusion uses the power of Responders in Rails 3 to enable a macro for specifying that resources rendered as xml or json include associated resources. This may be used in conjunction with Inherited Resources to keep your controllers lean and mean.

Given a model such as:

create_table :users do |t|
  t.string  :login_id
  t.string  :display_name    
  t.string  :email
end

create_table :comments do |t|
  t.text       :text
  t.references :user
end

Our CommentsController need only have the following to include the user’s attributes:

class CommentsController < ApplicationController

  inherit_resources

  include_resources :user

  #  If you like to type, you could have written the following, but you still
  #  would lack the behavior for other actions which return the resources.
  #
  #  def index
  #    index! do |format|
  #      format.xml{  render :xml  => collection.to_xml(  render_options ) }
  #      format.json{ render :json => collection.to_json( render_options ) }
  #    end
  #  end
  #
  #  def show
  #    show! do |format|
  #      format.xml{ render :xml  => resource.to_xml(  render_options ) }
  #      format.xml{ render :json => resource.to_json( render_options ) }
  #    end
  #  end
  #
  #  def render_options
  #    { :include => [:user] }
  #  end
  #

end

Thus /comments/1.xml would render:

<?xml version="1.0" encoding="UTF-8"?> 
<comment> 
  <id type="integer">1</id> 
  <text>This is comment text.</text> 
  <user-id type="integer">1</user-id> 
  <user> 
    <login-id>aperson</login-id> 
    <display-name>A. Person</display-name> 
    <email>a.person@somedomain.com</email> 
    <id type="integer">1</id> 
  </user> 
</comment>

The output for the json format would be analogous.

Installation¶ ↑

Resource Inclusion requires Rails 3.

You can let bundler to install Resource Inclusion by adding this line to your application’s Gemfile:

gem 'resource_inclusion', '0.0.1'

And then execute:

bundle install

Add resource_inclusion to your app/controllers/application_controller.rb file (or to any of your other controllers):

class ApplicationController < ActionController::Base

   resource_inclusion

end

Then use the macro to your controllers as shown above.

Limitations¶ ↑

In this release of Resource Inclusion the macros support no configuration options beyond what you can pass to serializer (#to_xml or #to_json) with the :include option. These options will be passed to the serializer for any action that uses ActionController#respond_with and with all formats, excluding HTML.

For more on #respond_with see:

Note that this plug-in has no dependency on Inherited Resources and should work just fine without it. That said, I have not tested with in an application which doesn’t use Inherited Resources so I’ll be interested in feedback from users.

Acknowledgments¶ ↑

Thanks to Jose Valim for pointing me in the right direction and his must-have Inherit Resources plug-in. If are on Rails 3, wish to expose an REST API and are not using this plug-in, you probably writing more code than you should be. See:

Bugs and Feedback¶ ↑

Feedback is welcome. If you discover any bugs or want to drop a line, file issues on GitHub or contact me personally via GitHub.

Copyright © 2010 John-Mason P. Shackelford

See the attached MIT License.