Jbuilder

Jbuilder gives you a simple DSL for declaring JSON structures that beats manipulating giant hash structures. This is particularly helpful when the generation process is fraught with conditionals and loops. Here's a simple example:

# app/views/messages/show.json.jbuilder

json.content format_content(@message.content)
json.(@message, :created_at, :updated_at)
json.author do
  json.name @message.creator.name.familiar
  json.email_address @message.creator.email_address_with_name
  json.url url_for(@message.creator, format: :json)
end
if current_user.admin?
  json.visitors calculate_visitors(@message)
end
json.comments @message.comments, :content, :created_at
json.attachments @message.attachments do |attachment|
  json.filename attachment.filename
  json.url url_for(attachment)
end

This will build the following structure:

{
  "content": "
This is serious monkey business
",
  "created_at": "2011-10-29T20:45:28-05:00",
  "updated_at": "2011-10-29T20:45:28-05:00",

  "author": {
    "name": "David H.",
    "email_address": "'David Heinemeier Hansson' ",
    "url": "http://example.com/users/1-david.json"
  },
  "visitors": 15,
  "comments": [
    { "content": "Hello everyone!", "created_at": "2011-10-29T20:45:28-05:00" },
    { "content": "To you my good sir!", "created_at": "2011-10-29T20:47:28-05:00" }
  ],
  "attachments": [
    { "filename": "forecast.xls", "url": "http://example.com/downloads/forecast.xls" },
    { "filename": "presentation.pdf", "url": "http://example.com/downloads/presentation.pdf" }
  ]
}

To define attribute and structure names dynamically, use the

set!

json.set! :author do
  json.set! :name, 'David'
end

=> {"author": { "name": "David" }}

To merge existing hash or array to current context:

hash = { author: { name: "David" } }
json.post do
  json.title "Merge HOWTO"
  json.merge! hash
end

=> "post": { "title": "Merge HOWTO", "author": { "name": "David" } }

Top level arrays can be handled directly. Useful for index and other collection actions.

# @comments = @post.comments

json.array! @comments do |comment|
  next if comment.marked_as_spam_by?(current_user)
  json.body comment.body
  json.author do
    json.first_name comment.author.first_name
    json.last_name comment.author.last_name
  end
end
=> [ { "body": "great post...", "author": { "first_name": "Joe", "last_name": "Bloe" }} ]

You can also extract attributes from array directly.

# @people = People.all

json.array! @people, :id, :name
=> [ { "id": 1, "name": "David" }, { "id": 2, "name": "Jamie" } ]

You don't always have or need a collection when building an array.

json.people do
  json.child! do
    json.id 1
    json.name 'David'
  end
  json.child! do
    json.id 2
    json.name 'Jamie'
  end
end

=> { "people": [ { "id": 1, "name": "David" }, { "id": 2, "name": "Jamie" } ] }

Jbuilder objects can be directly nested inside each other. Useful for composing objects.

class Person
  # ... Class Definition ... #
  def to_builder
    Jbuilder.new do |person|
      person.(self, :name, :age)
    end
  end
end

class Company
... Class Definition ...
  def to_builder
    Jbuilder.new do |company|
      company.name name
      company.president president.to_builder
    end
  end
end
company = Company.new('Doodle Corp', Person.new('John Stobs', 58))
company.to_builder.target!
=> {"name":"Doodle Corp","president":{"name":"John Stobs","age":58}}

You can either use Jbuilder stand-alone or directly as an ActionView template language. When required in Rails, you can create views a la show.json.jbuilder (the json is already yielded):

# Any helpers available to views are available to the builder
json.content format_content(@message.content)
json.(@message, :created_at, :updated_at)

json.author do
  json.name @message.creator.name.familiar
  json.email_address @message.creator.email_address_with_name
  json.url url_for(@message.creator, format: :json)
end
if current_user.admin?
  json.visitors calculate_visitors(@message)
end

You can use partials as well. The following will render the file

views/comments/_comments.json.jbuilder

comments

json.partial! 'comments/comments', comments: @message.comments

It's also possible to render collections of partials:

json.array! @posts, partial: 'posts/post', as: :post

or
json.partial! 'posts/post', collection: @posts, as: :post
or
json.partial! partial: 'posts/post', collection: @posts, as: :post
or
json.comments @post.comments, partial: 'comments/comment', as: :comment

The

as: :some_symbol

collection:

some_symbol

some_symbol

Be sure not to confuse the

as:

 # Use the default `views/comments/_comment.json.jbuilder`, putting @comment as the comment local variable.
 # Note, `comment` attributes are "inlined".
 json.partial! @comment, as: :comment

is quite different than:

 # comment attributes are nested under a "comment" property
json.comment do
  json.partial! "/comments/comment.json.jbuilder", comment: @comment
end

You can pass any objects into partial templates with or without

:locals

json.partial! 'sub_template', locals: { user: user }

or
json.partial! 'sub_template', user: user

You can explicitly make Jbuilder object return null if you want:

json.extract! @post, :id, :title, :content, :published_at
json.author do
  if @post.anonymous?
    json.null! # or json.nil!
  else
    json.first_name @post.author_first_name
    json.last_name @post.author_last_name
  end
end

To prevent Jbuilder from including null values in the output, you can use the

ignore_nil!

json.ignore_nil!
json.foo nil
json.bar "bar"
# => { "bar": "bar" }

Fragment caching is supported, it uses

Rails.cache

json.cache! ['v1', @person], expires_in: 10.minutes do
  json.extract! @person, :name, :age
end

You can also conditionally cache a block by using

cache_if!

json.cache_if! !admin?, ['v1', @person], expires_in: 10.minutes do
  json.extract! @person, :name, :age
end

If you are rendering fragments for a collection of objects, have a look at

jbuilder_cache_multi

Keys can be auto formatted using

key_format!

json.key_format! camelize: :lower
json.first_name 'David'

=> { "firstName": "David" }

You can set this globally with the class method

key_format

Jbuilder.key_format camelize: :lower

By default, key format is not applied to keys of hashes that are passed to methods like

set!

array!

merge!

json.key_format! camelize: :lower
json.deep_format_keys!
json.settings([{some_value: "abc"}])

=> { "settings": [{ "someValue": "abc" }]}

You can set this globally with the class method

deep_format_keys

Jbuilder.deep_format_keys true

Contributing to Jbuilder

Jbuilder is the work of many contributors. You're encouraged to submit pull requests, propose features and discuss issues.

See CONTRIBUTING.

License

Jbuilder is released under the MIT License.