Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 99 lines (78 sloc) 3.198 kb
34729c3 @dhh Rename to Jbuilder after discovering @dewski's JSONBuilder
dhh authored
1 Jbuilder
5c39a37 @dhh Improve docs
dhh authored
2 ========
c9690b4 @dhh Markup it is
dhh authored
3
34729c3 @dhh Rename to Jbuilder after discovering @dewski's JSONBuilder
dhh authored
4 Jbuilder gives you a simple DSL for declaring JSON structures that beats massaging giant hash structures. This is particularly helpful when the generation process is fraught with conditionals and loops. Here's a simple example:
c9690b4 @dhh Markup it is
dhh authored
5
e3d4093 @soffes Add code coloring to Readme
soffes authored
6 ``` ruby
7 Jbuilder.encode do |json|
8 json.content format_content(@message.content)
9 json.(@message, :created_at, :updated_at)
10
11 json.author do |json|
12 json.name @message.creator.name.familiar
13 json.email_address @message.creator.email_address_with_name
14 json.url url_for(@message.creator, format: :json)
15 end
16
17 if current_user.admin?
18 json.visitors calculate_visitors(@message)
19 end
20
21 json.comments @message.comments, :content, :created_at
c9690b4 @dhh Markup it is
dhh authored
22
e3d4093 @soffes Add code coloring to Readme
soffes authored
23 json.attachments @message.attachments do |json, attachment|
24 json.filename attachment.filename
25 json.url url_for(attachment)
26 end
27 end
28 ```
c9690b4 @dhh Markup it is
dhh authored
29
30 This will build the following structure:
31
e3d4093 @soffes Add code coloring to Readme
soffes authored
32 ``` javascript
33 {
34 "content": "<p>This is <i>serious</i> monkey business",
35 "created_at": "2011-10-29T20:45:28-05:00",
36 "updated_at": "2011-10-29T20:45:28-05:00",
37
38 "author": {
39 "name": "David H.",
40 "email_address": "'David Heinemeier Hansson' <david@heinemeierhansson.com>",
41 "url": "http://example.com/users/1-david.json"
42 },
43
44 "visitors": 15,
45
46 "comments": [
47 { "content": "Hello everyone!", "created_at": "2011-10-29T20:45:28-05:00" },
48 { "content": "To you my good sir!", "created_at": "2011-10-29T20:47:28-05:00" }
49 ],
50
13f3c3b @backspace Fix typo in JSON output
backspace authored
51 "attachments": [
e3d4093 @soffes Add code coloring to Readme
soffes authored
52 { "filename": "forecast.xls", "url": "http://example.com/downloads/forecast.xls" },
53 { "filename": "presentation.pdf", "url": "http://example.com/downloads/presentation.pdf" }
54 ]
55 }
56 ```
c9690b4 @dhh Markup it is
dhh authored
57
9942e48 @anithri Update README.md to talk about #array! for use in index or other collect...
anithri authored
58 Top level arrays can be handled directly. Useful for index and other collection actions.
59
60 ``` ruby
9ce1fcc @dhh Clean up README and bump version to 0.4.0 for the merged fixes
dhh authored
61 # @people = People.all
9942e48 @anithri Update README.md to talk about #array! for use in index or other collect...
anithri authored
62 json.array!(@people) do |json, person|
63 json.name person.name
64 json.age calculate_age(person.birthday)
65 end
9ce1fcc @dhh Clean up README and bump version to 0.4.0 for the merged fixes
dhh authored
66 # => [ { "name": David", "age": 32 }, { "name": Jamie", "age": 31 } ]
9942e48 @anithri Update README.md to talk about #array! for use in index or other collect...
anithri authored
67 ```
68
34729c3 @dhh Rename to Jbuilder after discovering @dewski's JSONBuilder
dhh authored
69 You can either use Jbuilder stand-alone or directly as an ActionView template language. When required in Rails, you can create views ala show.json.jbuilder (the json is already yielded):
c9690b4 @dhh Markup it is
dhh authored
70
e3d4093 @soffes Add code coloring to Readme
soffes authored
71 ``` ruby
72 # Any helpers available to views are available to the builder
73 json.content format_content(@message.content)
74 json.(@message, :created_at, :updated_at)
c9690b4 @dhh Markup it is
dhh authored
75
e3d4093 @soffes Add code coloring to Readme
soffes authored
76 json.author do |json|
77 json.name @message.creator.name.familiar
78 json.email_address @message.creator.email_address_with_name
79 json.url url_for(@message.creator, format: :json)
80 end
c9690b4 @dhh Markup it is
dhh authored
81
e3d4093 @soffes Add code coloring to Readme
soffes authored
82 if current_user.admin?
83 json.visitors calculate_visitors(@message)
84 end
c9690b4 @dhh Markup it is
dhh authored
85
e37b037 @lagartoflojo Explain how to use partial!
lagartoflojo authored
86 # You can use partials as well. The following line will render the file
5c5177b @lagartoflojo Missing commas.
lagartoflojo authored
87 # RAILS_ROOT/app/views/api/comments/_comments, and set a local variable
88 # 'comments' with all this message's comments, which you can use inside
e37b037 @lagartoflojo Explain how to use partial!
lagartoflojo authored
89 # the partial.
b9e5f5e @lagartoflojo Clarify partial usage
lagartoflojo authored
90 json.partial! "api/comments/comments", comments: @message.comments
e3d4093 @soffes Add code coloring to Readme
soffes authored
91 ```
ac93665 @dhh Expand example
dhh authored
92
614f2cb @AquaGeek Fix minor typo in Readme
AquaGeek authored
93 Libraries similar to this in some form or another include:
960602c @dhh List the other Builder-like options for generating JSON in the README
dhh authored
94
95 * RABL: https://github.com/nesquena/rabl
96 * JsonBuilder: https://github.com/nov/jsonbuilder
97 * JSON Builder: https://github.com/dewski/json_builder
98 * Jsonify: https://github.com/bsiggelkow/jsonify
9ce1fcc @dhh Clean up README and bump version to 0.4.0 for the merged fixes
dhh authored
99 * RepresentationView: https://github.com/mdub/representative_view
Something went wrong with that request. Please try again.