Blueprinter Documentation

Transformers allow you to process the resulting hash of a view before it is serialized. Create a class inheriting from Blueprinter::Transformer and implement the transform(hash, object, options) method. Transformers can be applied globally, per-blueprint, or per-view.

class DynamicFieldTransformer < Blueprinter::Transformer
  def transform(hash, object, _options)
    hash.merge!(object.dynamic_fields)
  end
end

class UserBlueprint < Blueprinter::Base
  fields :first_name, :last_name
  transform DynamicFieldTransformer
end

The extension system allows you to intercept the rendering process. Currently, the pre_render hook is available, which allows you to modify or replace the object before serialization begins. Extensions are executed in the order they are added to Blueprinter.configure.extensions.

class ObfuscateNameExtension < Blueprinter::Extension
  def pre_render(object, blueprint, view, options)
    return object unless object.respond_to?(:name)

    modified_object = object.dup
    modified_object.name = ObsfuscateName.call(modified_object.name)

    modified_object
  end
end

Blueprinter.configure do |config|
  config.extensions << ObfuscateNameExtension.new
end

Views allow you to define different output shapes for the same blueprint. You can use view :name do ... end to define a view and include_view :other_view to compose views by inheriting fields from another.

class UserBlueprint < Blueprinter::Base
  identifier :uuid
  field :email, name: :login

  view :normal do
    fields :first_name, :last_name
  end

  view :extended do
    include_view :normal
    field :address
    association :projects
  end
end

# Usage
puts UserBlueprint.render(user, view: :extended)

Associations allow you to include related objects. You can specify the blueprint to use for the association and pass static options or a Proc to derive options from the parent object at runtime.

class DriverBlueprint < Blueprinter::Base
  identifier :uuid

  view :normal do
    fields :first_name, :last_name
    # Passing options via a Proc to derive them from the parent object
    association :vehicles, 
                blueprint: VehicleBlueprint, 
                options: ->(driver) { { trim: driver.preferred_trim } }
  end
end

An identifier specifies the field or method used as the object's unique ID. Identifiers have two unique properties:

1. They are always rendered and are considered their own view (:identifier).
2. They are always sorted first in the output JSON.

If you do not want this behavior, define the ID as a regular field instead.

class UserBlueprint < Blueprinter::Base
  identifier :uuid
end

To serialize an object, create a class inheriting from Blueprinter::Base. Use identifier to specify the unique ID field and fields to list the attributes to be included. Call .render(object) on the blueprint class to get a JSON string.

class UserBlueprint < Blueprinter::Base
  identifier :uuid

  fields :first_name, :last_name, :email
end

puts UserBlueprint.render(user) # Output is a JSON string

To install Blueprinter, add it to your application's Gemfile:

gem 'blueprinter'

Then run bundle in your terminal. Alternatively, you can install it directly using gem install blueprinter.

Note: If you are not using Rails or the Oj gem, ensure you have require 'json' in your project.

You can control how Blueprinter reports deprecated functionality using the deprecations configuration key. Options are:

• :stderr (Default): Writes to stderr.
• :raise: Raises a Blueprinter::BlueprinterError.
• :silence: Silences all deprecation notices.

Blueprinter.configure do |config|
  config.deprecations = :raise
end

By default, Blueprinter sorts JSON keys alphabetically. To preserve the order in which fields are defined in your blueprint, configure sort_fields_by = :definition.

Blueprinter.configure do |config|
  config.sort_fields_by = :definition
end

To use yajl-ruby instead of the default JSON or Oj generators, configure the generator and the method used for encoding.

_Note: If you are using yajl-ruby via its JSON compatibility API (require 'yajl/json_gem'), JSON.generate is already patched to use Yajl::Encoder.encode, so manual configuration may not be necessary.

require 'yajl' # you can skip this if yajl has already been required.

Blueprinter.configure do |config|
  config.generator = Yajl::Encoder # default is JSON
  config.method = :encode # default is generate
end