README.md in jbuilder-2.11.2 vs README.md in jbuilder-2.11.3
- old
+ new
@@ -106,10 +106,36 @@
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.
+
+``` ruby
+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.
+
+```ruby
+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.
``` ruby
class Person
# ... Class Definition ... #
@@ -135,11 +161,11 @@
# => {"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
+language. When required in Rails, you can create views à la show.json.jbuilder
(the json is already yielded):
``` ruby
# Any helpers available to views are available to the builder
json.content format_content(@message.content)
@@ -169,33 +195,33 @@
```ruby
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`.
+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:
```ruby
# 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:
+is quite different from:
```ruby
# comment attributes are nested under a "comment" property
json.comment do
json.partial! "/comments/comment.json.jbuilder", comment: @comment
@@ -234,10 +260,12 @@
json.foo nil
json.bar "bar"
# => { "bar": "bar" }
```
+## Caching
+
Fragment caching is supported, it uses `Rails.cache` and works like caching in
HTML templates:
```ruby
json.cache! ['v1', @person], expires_in: 10.minutes do
@@ -251,12 +279,20 @@
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` gem. It uses fetch_multi (>= Rails 4.1) to fetch
-multiple keys at once.
+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
+```
+
+## Formatting Keys
Keys can be auto formatted using `key_format!`, this can be used to convert
keynames from the standard ruby_format to camelCase:
``` ruby