Class: Jbuilder

Inherits:
BasicObject
Defined in:
lib/jbuilder.rb,
lib/jbuilder/blank.rb,
lib/jbuilder/errors.rb,
lib/jbuilder/railtie.rb,
lib/jbuilder/version.rb,
lib/jbuilder/key_formatter.rb,
lib/jbuilder/collection_renderer.rb

Direct Known Subclasses

JbuilderTemplate

Defined Under Namespace

Classes: ArrayError, Blank, CollectionRenderer, DependencyTracker, EnumerableCompat, KeyFormatter, MergeError, NullError, Railtie

Constant Summary collapse

VERSION = 
"2.15.0"
@@key_formatter = 
nil
@@ignore_nil = 
false
@@deep_format_keys = 
false

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key_formatter: @@key_formatter, ignore_nil: @@ignore_nil, deep_format_keys: @@deep_format_keys) {|_self| ... } ⇒ Jbuilder

Returns a new instance of Jbuilder.

Yields:

  • (_self)

Yield Parameters:

  • _self (Jbuilder) —

    the object that the method was called on



17
18
19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/jbuilder.rb', line 17

def initialize(
  key_formatter: @@key_formatter,
  ignore_nil: @@ignore_nil,
  deep_format_keys: @@deep_format_keys,
  &block
)
  @attributes = {}
  @key_formatter = key_formatter
  @ignore_nil = ignore_nil
  @deep_format_keys = deep_format_keys

  yield self if block
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing ⇒ Object (private) 



237
238
239
 
# File 'lib/jbuilder.rb', line 237

def set!(key, value = BLANK, *args, &block)
  _set(key, value, args, &block)
end

Class Method Details

.deep_format_keys(value = true) ⇒ Object

Same as instance method deep_format_keys! except sets the default.



126
127
128
 
# File 'lib/jbuilder.rb', line 126

def self.deep_format_keys(value = true)
  @@deep_format_keys = value
end

.encode ⇒ Object

Yields a builder and automatically turns the result into a JSON string



32
33
34
 
# File 'lib/jbuilder.rb', line 32

def self.encode(...)
  new(...).target!
end

.ignore_nil(value = true) ⇒ Object

Same as instance method ignore_nil! except sets the default.



101
102
103
 
# File 'lib/jbuilder.rb', line 101

def self.ignore_nil(value = true)
  @@ignore_nil = value
end

.key_format ⇒ Object

Same as the instance method key_format! except sets the default.



77
78
79
 
# File 'lib/jbuilder.rb', line 77

def self.key_format(...)
  @@key_formatter = KeyFormatter.new(...)
end

Instance Method Details

#array!(collection = EMPTY_ARRAY, *attributes, &block) ⇒ Object

Turns the current element into an array and iterates over the passed collection, adding each iteration as an element of the resulting array.

Example:

json.array!(@people) do |person|
  json.name person.name
  json.age calculate_age(person.birthday)
end

[ { "name": David", "age": 32 }, { "name": Jamie", "age": 31 } ]

You can use the call syntax instead of an explicit extract! call:

json.(@people) { |person| ... }

It’s generally only needed to use this method for top-level arrays. If you have named arrays, you can do:

json.people(@people) do |person|
  json.name person.name
  json.age calculate_age(person.birthday)
end

{ "people": [ { "name": David", "age": 32 }, { "name": Jamie", "age": 31 } ] }

If you omit the block then you can set the top level array directly:

json.array! [1, 2, 3]

[1,2,3]



181
182
183
 
# File 'lib/jbuilder.rb', line 181

def array!(collection = EMPTY_ARRAY, *attributes, &block)
  _array collection, attributes, &block
end

#attributes! ⇒ Object

Returns the attributes of the current builder.



222
223
224
 
# File 'lib/jbuilder.rb', line 222

def attributes!
  @attributes
end

#call(object, *attributes, &block) ⇒ Object 



206
207
208
209
210
211
212
 
# File 'lib/jbuilder.rb', line 206

def call(object, *attributes, &block)
  if block
    _array object, &block
  else
    _extract object, attributes
  end
end

#child! ⇒ Object

Turns the current element into an array and yields a builder to add a hash.

Example:

json.comments do
  json.child! { json.content "hello" }
  json.child! { json.content "world" }
end

{ "comments": [ { "content": "hello" }, { "content": "world" } ]}

More commonly, you’d use the combined iterator, though:

json.comments(@post.comments) do |comment|
  json.content comment.formatted_content
end



146
147
148
149
 
# File 'lib/jbuilder.rb', line 146

def child!
  @attributes = [] unless ::Array === @attributes
  @attributes << _scope{ yield self }
end

#deep_format_keys!(value = true) ⇒ Object

Deeply apply key format to nested hashes and arrays passed to methods like set!, merge! or array!.

Example:

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

{ "settings": { "some_value": "abc" }}

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

{ "settings": { "someValue": "abc" }}



121
122
123
 
# File 'lib/jbuilder.rb', line 121

def deep_format_keys!(value = true)
  @deep_format_keys = value
end

#extract!(object, *attributes) ⇒ Object

Extracts the mentioned attributes or hash elements from the passed object and turns them into attributes of the JSON.

Example:

@person = Struct.new(:name, :age).new('David', 32)

or you can utilize a Hash

@person = { name: 'David', age: 32 }

json.extract! @person, :name, :age

{ "name": David", "age": 32 }, { "name": Jamie", "age": 31 }

You can also use the call syntax instead of an explicit extract! call:

json.(@person, :name, :age)



202
203
204
 
# File 'lib/jbuilder.rb', line 202

def extract!(object, *attributes)
  _extract object, attributes
end

#ignore_nil!(value = true) ⇒ Object

If you want to skip adding nil values to your JSON hash. This is useful for JSON clients that don’t deal well with nil values, and would prefer not to receive keys which have null values.

Example:

json.ignore_nil! false
json.id User.new.id

{ "id": null }

json.ignore_nil!
json.id User.new.id

{}



96
97
98
 
# File 'lib/jbuilder.rb', line 96

def ignore_nil!(value = true)
  @ignore_nil = value
end

#key_format! ⇒ Object

Specifies formatting to be applied to the key. Passing in a name of a function will cause that function to be called on the key. So :upcase will upper case the key. You can also pass in lambdas for more complex transformations.

Example:

json.key_format! :upcase
json.author do
  json.name "David"
  json.age 32
end

{ "AUTHOR": { "NAME": "David", "AGE": 32 } }

You can pass parameters to the method using a hash pair.

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

{ "firstName": "David" }

Lambdas can also be used.

json.key_format! ->(key){ "_" + key }
json.first_name "David"

{ "_first_name": "David" }



72
73
74
 
# File 'lib/jbuilder.rb', line 72

def key_format!(...)
  @key_formatter = KeyFormatter.new(...)
end

#merge!(object) ⇒ Object

Merges hash, array, or Jbuilder instance into current builder.



227
228
229
230
 
# File 'lib/jbuilder.rb', line 227

def merge!(object)
  hash_or_array = ::Jbuilder === object ? object.attributes! : object
  @attributes = _merge_values(@attributes, _format_keys(hash_or_array))
end

#nil! ⇒ Object Also known as: null!

Returns the nil JSON.



215
216
217
 
# File 'lib/jbuilder.rb', line 215

def nil!
  @attributes = nil
end

#set!(key, value = BLANK, *args, &block) ⇒ Object Also known as: method_missing 



40
41
42
 
# File 'lib/jbuilder.rb', line 40

def set!(key, value = BLANK, *args, &block)
  _set(key, value, args, &block)
end

#target! ⇒ Object

Encodes the current builder as JSON.



233
234
235
 
# File 'lib/jbuilder.rb', line 233

def target!
  @attributes.to_json
end