• Stars
    star
    4,298
  • Rank 9,537 (Top 0.2 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 12 years ago
  • Updated about 1 month ago

Reviews 3.0 (1)

9 months ago by Igor Kasyanchuk

oh, don't like this gem. I think it's too complex and not very flexible.

I prefer to just write "render json: ..."

Repository Details

Jbuilder: generate JSON objects with a Builder-style DSL

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": "<p>This is <i>serious</i> monkey business</p>",
  "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' <[email protected]>",
    "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! method:

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" } ]

To make a plain array without keys, construct and pass in a standard Ruby array.

my_array = %w(David Jamie)

json.people my_array

# => "people": [ "David", "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 à 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, and set a local variable comments with all this message's comments, which you can use inside the partial.

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 is used with partials. It will take care of mapping the passed in object to a variable for the partial. If the value is a collection either implicitly or explicitly by using the collection: option, then each value of the collection is passed to the partial as the variable some_symbol. If the value is a singular object, then the object is passed to the partial as the variable some_symbol.

Be sure not to confuse the as: option to mean nesting of the partial. For example:

 # 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 from:

 # 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 option.

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! method:

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

Caching

Fragment caching is supported, it uses Rails.cache and works like caching in HTML templates:

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! like this:

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

Aside from that, the :cached options on collection rendering is available on Rails >= 6.0. This will cache the rendered results effectively using the multi fetch feature.

json.array! @posts, partial: "posts/post", as: :post, cached: true

# or:
json.comments @post.comments, partial: "comments/comment", as: :comment, cached: true

If your collection cache depends on multiple sources (try to avoid this to keep things simple), you can name all these dependencies as part of a block that returns an array:

json.array! @posts, partial: "posts/post", as: :post, cached: -> post { [post, current_user] }

This will include both records as part of the cache key and updating either of them will expire the cache.

Formatting Keys

Keys can be auto formatted using key_format!, this can be used to convert keynames from the standard ruby_format to camelCase:

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

# => { "firstName": "David" }

You can set this globally with the class method key_format (from inside your environment.rb for example):

Jbuilder.key_format camelize: :lower

By default, key format is not applied to keys of hashes that are passed to methods like set!, array! or merge!. You can opt into deeply transforming these as well:

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 (from inside your environment.rb for example):

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.

More Repositories

1

rails

Ruby on Rails
Ruby
54,600
star
2

webpacker

Use Webpack to manage app-like JavaScript modules in Rails
Ruby
5,313
star
3

thor

Thor is a toolkit for building powerful command-line interfaces.
Ruby
5,066
star
4

spring

Rails application preloader
Ruby
2,782
star
5

jquery-ujs

Ruby on Rails unobtrusive scripting adapter for jQuery
JavaScript
2,610
star
6

rails-dev-box

A virtual machine for Ruby on Rails core development
Shell
2,049
star
7

tailwindcss-rails

Ruby
1,343
star
8

kredis

Higher-level data structures built on Redis
Ruby
1,341
star
9

activeresource

Connects business objects and REST web services
Ruby
1,309
star
10

strong_parameters

Taint and required checking for Action Pack and enforcement in Active Model
Ruby
1,271
star
11

docked

Running Rails from Docker for easy start to development
Dockerfile
1,262
star
12

globalid

Identify app models with a URI
Ruby
1,164
star
13

actioncable

Framework for real-time communication over websockets
1,087
star
14

importmap-rails

Use ESM with importmap to manage modern JavaScript in Rails without transpiling or bundling.
Ruby
990
star
15

jquery-rails

A gem to automate using jQuery with Rails
Ruby
946
star
16

sprockets

Rack-based asset packaging system
Ruby
919
star
17

sass-rails

Ruby on Rails stylesheet engine for Sass
Ruby
858
star
18

exception_notification

NOTICE: official repository moved to https://github.com/smartinez87/exception_notification
Ruby
844
star
19

sdoc

Standalone sdoc generator
JavaScript
820
star
20

propshaft

Deliver assets for Rails
Ruby
785
star
21

jsbundling-rails

Bundle and transpile JavaScript in Rails with esbuild, rollup.js, or Webpack.
Ruby
778
star
22

rails-perftest

Benchmark and profile your Rails apps
Ruby
775
star
23

activejob

Declare job classes that can be run by a variety of queueing backends
Ruby
746
star
24

activestorage

Store files in Rails applications
734
star
25

solid_cache

A database-backed ActiveSupport::Cache::Store
Ruby
682
star
26

pjax_rails

PJAX integration for Rails
Ruby
670
star
27

actioncable-examples

Action Cable Examples
Ruby
663
star
28

cache_digests

Ruby
644
star
29

sprockets-rails

Sprockets Rails integration
Ruby
569
star
30

cssbundling-rails

Bundle and process CSS in Rails with Tailwind, PostCSS, and Sass via Node.js.
Ruby
539
star
31

activerecord-session_store

Active Record's Session Store extracted from Rails
Ruby
524
star
32

rails-observers

Rails observer (removed from core in Rails 4.0)
Ruby
513
star
33

execjs

Run JavaScript code from Ruby
Ruby
509
star
34

actiontext

Edit and display rich text in Rails applications
406
star
35

acts_as_list

NOTICE: official repository moved to https://github.com/swanandp/acts_as_list
Ruby
384
star
36

marcel

Find the mime type of files, examining file, filename and declared type
Ruby
369
star
37

request.js

JavaScript
356
star
38

actionpack-page_caching

Static page caching for Action Pack (removed from core in Rails 4.0)
Ruby
343
star
39

commands

Run Rake/Rails commands through the console
Ruby
338
star
40

ssl_requirement

NOTICE: official repository moved to https://github.com/retr0h/ssl_requirement
Ruby
315
star
41

rubocop-rails-omakase

Omakase Ruby styling for Rails
Ruby
310
star
42

rails-controller-testing

Brings back `assigns` and `assert_template` to your Rails tests
Ruby
295
star
43

rails-html-sanitizer

Ruby
294
star
44

open_id_authentication

NOTICE: official repository moved to https://github.com/Velir/open_id_authentication
Ruby
284
star
45

acts_as_tree

NOTICE: official repository moved to https://github.com/amerine/acts_as_tree
Ruby
279
star
46

actionpack-action_caching

Action caching for Action Pack (removed from core in Rails 4.0)
Ruby
260
star
47

in_place_editing

NOTICE: official repository moved to https://github.com/amerine/in_place_editing
Ruby
230
star
48

protected_attributes

Protect attributes from mass-assignment in ActiveRecord models.
Ruby
230
star
49

journey

A router for rails
Ruby
221
star
50

auto_complete

NOTICE: official repository moved to https://github.com/david-kerins/auto_complete
Ruby
211
star
51

dartsass-rails

Integrate Dart Sass with the asset pipeline in Rails
Ruby
192
star
52

dynamic_form

NOTICE: official repository moved to https://github.com/joelmoss/dynamic_form
Ruby
192
star
53

country_select

NOTICE: official repository moved to https://github.com/stefanpenner/country_select
Ruby
176
star
54

rails-dom-testing

Extracting DomAssertions and SelectorAssertions from ActionView.
Ruby
168
star
55

routing_concerns

Abstract common routing resource concerns to cut down on duplication.
Ruby
154
star
56

esbuild-rails

Bundle and transpile JavaScript in Rails with esbuild
Ruby
147
star
57

rails-contributors

The web application that runs https://contributors.rubyonrails.org
Ruby
138
star
58

actionmailbox

Receive and process incoming emails in Rails
125
star
59

requestjs-rails

JavaScript
103
star
60

activemodel-globalid

Serializing models to a single string makes it easy to pass references around
Ruby
90
star
61

account_location

NOTICE: official repository moved to https://github.com/bbommarito/account_location
Ruby
73
star
62

acts_as_nested_set

NOTICE: official repository moved to https://github.com/bbommarito/acts_as_nested_set
Ruby
71
star
63

iso-3166-country-select

WARNING: this repo is not maintained anymore, if you want to maintain it, please send an mail to rails-core
Ruby
70
star
64

activerecord-deprecated_finders

Ruby
68
star
65

spring-watcher-listen

Ruby
63
star
66

weblog

Superseded by https://github.com/rails/website
HTML
63
star
67

prototype-ujs

JavaScript
62
star
68

prototype_legacy_helper

WARNING: this repo is not maintained anymore, if you want to maintain it, please send an mail to rails-core
Ruby
60
star
69

verification

NOTICE: official repository moved to https://github.com/sikachu/verification
Ruby
58
star
70

website

HTML
55
star
71

prototype-rails

Add RJS, Prototype, and Scriptaculous helpers to Rails 3.1+ apps
Ruby
55
star
72

activemodel-serializers-xml

Ruby
52
star
73

record_tag_helper

ActionView Record Tag Helpers
Ruby
50
star
74

homepage

Superseded by https://github.com/rails/website
HTML
50
star
75

rollupjs-rails

Bundle and transpile JavaScript in Rails with rollup.js
Ruby
49
star
76

actionpack-xml_parser

XML parameters parser for Action Pack (removed from core in Rails 4.0)
Ruby
49
star
77

activesupport-json_encoder

Ruby
48
star
78

etagger

Declare what goes in to your ETags: asset versions, account ID, etc.
Ruby
41
star
79

upload_progress

NOTICE: official repository moved to https://github.com/rishav/upload_progress
Ruby
39
star
80

atom_feed_helper

NOTICE: official repository moved to https://github.com/TrevorBramble/atom_feed_helper
Ruby
38
star
81

render_component

NOTICE: official repository moved to https://github.com/malev/render_component. Components allow you to call other actions for their rendered response while executing another action
Ruby
38
star
82

gsoc2014

Project website and wiki for Ruby on Rails proposals to Google Summer of Code 2014
37
star
83

gsoc2013

Project website and wiki for Ruby on Rails proposals to Google Summer of Code 2013
31
star
84

ruby-coffee-script

Ruby CoffeeScript Compiler
Ruby
28
star
85

asset_server

NOTICE: official repository moved to https://github.com/andhapp/asset_server
Ruby
27
star
86

homepage-2011

This repo is now legacy. New homepage is at rails/homepage
HTML
26
star
87

deadlock_retry

NOTICE: official repository moved to https://github.com/heaps/deadlock_retry
Ruby
26
star
88

token_generator

NOTICE: official repository moved to https://github.com/bbommarito/token_generator
Ruby
25
star
89

rails-docs-server

Ruby
24
star
90

http_authentication

NOTICE: official repository moved to https://github.com/dshimy/http_authentication
Ruby
22
star
91

irs_process_scripts

WARNING: this repo is not maintained anymore, if you want to maintain it, please send an mail to rails-core. The extracted inspector, reaper, and spawner scripts from script/process/*
22
star
92

javascript_test

WARNING: this repo is not maintained anymore, if you want to maintain it, please send an mail to rails-core
JavaScript
19
star
93

rails_fast_attributes

Experimental project
Rust
18
star
94

scriptaculous_slider

WARNING: this repo is not maintained anymore, if you want to maintain it, please send an mail to rails-core
JavaScript
18
star
95

rails-ujs

Ruby on Rails unobtrusive scripting adapter
17
star
96

request_profiler

WARNING: this repo is not maintained anymore, if you want to maintain it, please send an mail to rails-core. Request profiler based on integration test scripts
Ruby
17
star
97

scaffolding

NOTICE: official repository moved to https://github.com/KeysetTS/scaffolding
Ruby
17
star
98

rails-new

Shell
16
star
99

buildkite-config

Fallback configuration for branches that lack a .buildkite/ directory
Ruby
16
star
100

tzinfo_timezone

WARNING: this repo is not maintained anymore, if you want to maintain it, please send an mail to rails-core
Ruby
13
star