Blueprinter is a JSON Object Presenter for Ruby that takes business objects and breaks them down into simple hashes and serializes them to JSON. It can be used in Rails in place of other serializers (like JBuilder or ActiveModelSerializers). It is designed to be simple, direct, and performant.
It heavily relies on the idea of views
which, similar to Rails views, are ways of predefining output for data in different contexts.
Docs can be found here.
If you have an object you would like serialized, simply create a blueprint. Say, for example, you have a User record with the following attributes [:uuid, :email, :first_name, :last_name, :password, :address]
.
You may define a simple blueprint like so:
class UserBlueprint < Blueprinter::Base
identifier :uuid
fields :first_name, :last_name, :email
end
and then, in your code:
puts UserBlueprint.render(user) # Output is a JSON string
And the output would look like:
{
"uuid": "733f0758-8f21-4719-875f-262c3ec743af",
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe"
}
You may define different ouputs by utilizing views:
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)
Output:
{
"uuid": "733f0758-8f21-4719-875f-262c3ec743af",
"address": "123 Fake St.",
"first_name": "John",
"last_name": "Doe",
"login": "[email protected]"
}
You may include associated objects. Say for example, a user has projects:
class ProjectBlueprint < Blueprinter::Base
identifier :uuid
field :name
end
class UserBlueprint < Blueprinter::Base
identifier :uuid
field :email, name: :login
view :normal do
fields :first_name, :last_name
association :projects, blueprint: ProjectBlueprint
end
end
Usage:
puts UserBlueprint.render(user, view: :normal)
Output:
{
"uuid": "733f0758-8f21-4719-875f-262c3ec743af",
"first_name": "John",
"last_name": "Doe",
"login": "[email protected]",
"projects": [
{
"uuid": "dca94051-4195-42bc-a9aa-eb99f7723c82",
"name": "Beach Cleanup"
},
{
"uuid": "eb881bb5-9a51-4d27-8a29-b264c30e6160",
"name": "Storefront Revamp"
}
]
}
You can define a field directly in the Blueprint by passing it a block. This is especially useful if the object does not already have such an attribute or method defined, and you want to define it specifically for use with the Blueprint. For example:
class UserBlueprint < Blueprinter::Base
identifier :uuid
field :full_name do |user|
"#{user.first_name} #{user.last_name}"
end
end
Usage:
puts UserBlueprint.render(user)
Output:
{
"uuid": "733f0758-8f21-4719-875f-262c3ec743af",
"full_name": "John Doe"
}
render
takes an options hash which you can pass additional properties, allowing you to utilize those additional properties in the field
block. For example:
class UserBlueprint < Blueprinter::Base
identifier :uuid
field(:company_name) do |_user, options|
options[:company].name
end
end
Usage:
puts UserBlueprint.render(user, company: company)
Output:
{
"uuid": "733f0758-8f21-4719-875f-262c3ec743af",
"company_name": "My Company LLC"
}
Add this line to your application's Gemfile:
gem 'blueprinter'
And then execute:
$ bundle
Or install it yourself as:
$ gem install blueprinter
You should also have require 'json'
already in your project if you are not using Rails or if you are not using Oj.
By default, Blueprinter will be calling JSON.generate(object)
internally and it expects that you have require 'json'
already in your project's code. You may use Oj
to generate in place of JSON
like so:
require 'oj' # you can skip this if OJ has already been required.
Blueprinter.configure do |config|
config.generator = Oj # default is JSON
end
Ensure that you have the Oj
gem installed in your Gemfile if you haven't already:
# Gemfile
gem 'oj'
We use Yard for documentation. Here are the following documentation rules:
- Document all public methods we expect to be utilized by the end developers.
- Methods that are not set to private due to ruby visibility rule limitations should be marked with
@api private
.
Feel free to browse the issues, converse, and make pull requests. If you need help, first please see if there is already an issue for your problem. Otherwise, go ahead and make a new issue.
You can run tests with bundle exec rake
.
We use Yard for documentation. Here are the following documentation rules:
- Document all public methods we expect to be utilized by the end developers.
- Methods that are not set to private due to ruby visibility rule limitations should be marked with
@api private
.
The gem is available as open source under the terms of the MIT License.