Easily define object decorators for JSON APIs using simple declarative syntax

Add this line to your application's Gemfile:

gem 'tint'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tint

You can use Tint by creating a decorator class that inherits from Tint::Decorator

To include methods and attributes available on the decorated object, simply list them using attributes.

# decorators/user_decorator.rb
class UserDecorator < Tint::Decorator
  attributes :username, :first_name, :last_name
end

You can map attributes to different names on the decorator by providing a hash as the final argument

# decorators/user_decorator.rb
class UserDecorator < Tint::Decorator
  attributes :username, :first_name, last_name: :surname # object.surname will be available as ['last_name']
end

The ids_for method adds *Ids values to a JSON object and ensures the corresponding association is automatically eager loaded:

class ProductDecorator < Tint::Decorator
  attributes :id, :description, :price

  ids_for :sales # will add a saleIds attribute to the JSON object
end

It's possible to give the *Ids attribute a different name by providing the name of the association as a key-value pair:

class ProductDecorator < Tint::Decorator
  attributes :id, :description, :price

  ids_for sales: :purchase_identifiers # will add a purchaseIdentifiers attribute to the JSON object
end

Tint will use a decorator instance method in preference to one defined on the decorated object, so it is possible to customise how a particular attribute appears. The original definition of the attribute is available via the object instance variable.

class ProductDecorator < Tint::Decorator
  attributes :id, :description, :price

  def price
    "$" + object.price
  end
end

It's also possible to define methods that are not available on the decorated object at all.

class ProductDecorator < Tint::Decorator
  attributes :id, :description, :on_sale

  def on_sale
    SaleItems.include?(object)
  end
end

The decorates_association method is used for declaring associations and delegating them to other decorators.

# decorators/product_decorator.rb
class ProductDecorator < Tint::Decorator
  attributes :id, :description
end

# decorators/user_decorator.rb
class UserDecorator < Tint::Decorator
  attributes :username

  decorates_association :products
end

By default, decorates_association uses the name of the association to guess the decorator it should use. In this case it will use ProductDecorator, but if you wished to render with SpecialProductDecorator, the with option may be used:

decorates_association :product, with: SpecialProductDecorator

You can decorate an association and make it available under a different name using the as option:

decorates_association :product, as: :sale_item

Multiple associations can be defined in the same statement using decorates_associations. Either, using interpolation to locate the correct decorator for each:

decorates_associations :product, :address

Or using the same decorator (in this case, AddressDecorator):

decorates_associations :previous_address, :current_address, with: AddressDecorator

When you declare a new association using decorates_association or decorates_associations, Tint automatically eager loads the associations when the decorator is rendered as JSON and automatically prevents many N+1 queries. It does this by maintaining a list eager_loads which is available on all decorators.

class UserDecorator < Tint::Decorator
  attributes :username

  decorates_association :products
end


UserDecorator.eager_loads # [:products]

If you need to manually add to the list of associations which are eager loaded for any reason, you can do so using the eager_load method

class UserDecorator < Tint::Decorator
  attributes :username

  decorates_association :products

  eager_load :addresses
end

UserDecorator.eager_loads # [:products, :addresses]

Tint maintains the interface defined by Draper for decorating objects. To decorate a single object, use the decorate method.

Using the UserDecorator defined above:

# controllers/users_controller.rb

class UsersController < ApplicationController

  def show
    @user = User.find(params[:id]) #<User username: "john_doe", first_name: "John", surname: "Doe">

    render json: UserDecorator.decorate(@user) # { username: "john_doe", firstName: "John", lastName: "Doe" }
  end

end

decorate also accepts an optional has of options. For more information about the supported options, see the Draper documentation.

The decorate_collection method is used for decorating an instance of ActiveRecord::Relation (or any class that implements the same interface). It accepts all of the same options as the decorate method.

# controllers/users_controller.rb

class UsersController < ApplicationController

  def index
    @users = User.all

    render json: UserDecorator.decorate_collection(@users) # [ { username: "john_doe", firstName: "John", lastName: "Doe" }, ... ]
  end

end

By default, Tint camelizes attribute names, however it's possible to configure Tint to use any of the following capitalization conventions:

Tint.configuration do |config|
  # attribute_naMe123 ==> attributeNaMe123 (Default)
  # config.attribute_capitalization = :camel_case

  # attribute_naMe123 ==> attribute_na_me123
  # config.attribute_capitalization = :snake_case

  # attribute_naMe123 ==> attribute-naMe123
  # config.attribute_capitalization = :kebab_case

  # Converts symbols to strings
  # config.attribute_capitalization = :none
end

The test suite may be run simply using

rspec

Tint remains in its infancy and all pull requests, issues and feedback are welcome and appreciated.