Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 142 lines (86 sloc) 4.137 kb
eec7acb @nesquena Initial commit to rabl
authored
1 # RABL #
2
3 RABL is a ruby templating system for Rails that takes a different approach for generating JSON and other formats. Rather than using the ActiveRecord 'to_json', I generally find myself wanting to use a more expressive and flexible system for generating my Public APIs. This is especially true when I the json doesn't match to the exact schema defined in the database.
4
5 There were a few things in particular I wanted to do easily:
6
7 * Create arbitrary nodes named based on combining data in the object
8 * Include nodes only if a condition is met
9 * Pass arguments to methods and store the result as a node
10 * Include partial templates to reduce code duplication
11 * Easily rename attributes from their name in the model
12
13 This general templating system solves all of those problems.
14
15 ## Installation ##
16
273c086 @nesquena Adds more notes about installation
authored
17 Install as a gem:
18
eec7acb @nesquena Initial commit to rabl
authored
19 gem install rabl
20
273c086 @nesquena Adds more notes about installation
authored
21 or add to your Gemfile:
22
23 # Gemfile
24 gem 'rabl'
25
26 and run `bundle install` to install the dependency.
27
d8c8a85 @nesquena Add note about Padrino/Rails/Tilt
authored
28 If you are using Rails 2.X or Padrino, RABL works out of the box. With Sinatra, or any other tilt-based framework, simply register:
29
30 Rabl.register!
31
32 and RABL will be initialized.
33
eec7acb @nesquena Initial commit to rabl
authored
34 ## Usage ##
35
f9e74fd @nesquena Adds note about object assignment
authored
36 ### Object Assignment ###
37
38 To declare the data object to use in the template:
39
40 # app/views/users/show.json.rabl
41 object @user
42
43 or a collection works:
44
45 object @users
46
47 and this will be used as the default data object for the rendering.
48
2b1b46f @nesquena Improve readme docs
authored
49 ### Attributes ###
50
3951fb7 @nesquena Updates and prepare for initial release
authored
51 Basic usage of the templater:
eec7acb @nesquena Initial commit to rabl
authored
52
3951fb7 @nesquena Updates and prepare for initial release
authored
53 # app/views/users/show.json.rabl
54 attributes :id, :foo, :bar
eec7acb @nesquena Initial commit to rabl
authored
55
2b1b46f @nesquena Improve readme docs
authored
56 or with aliased attributes:
3951fb7 @nesquena Updates and prepare for initial release
authored
57
2b1b46f @nesquena Improve readme docs
authored
58 # Take the value of model attribute `foo` and name the node `bar`
59 # { bar : 5 }
60 attribute :foo => :bar
0e36cb2 @nesquena Cleans up attribute doc
authored
61
62 or multiple aliased attributes:
63
64 # { baz : <bar value>, animal : <dog value> }
65 attributes :bar => :baz, :dog => :animal
3951fb7 @nesquena Updates and prepare for initial release
authored
66
2b1b46f @nesquena Improve readme docs
authored
67 ### Child Nodes ###
68
69 You can also add children nodes from an arbitrary object:
3951fb7 @nesquena Updates and prepare for initial release
authored
70
71 child @posts => :foobar do
72 attributes :id, :title
73 end
74
75 or use existing model associations:
76
77 child :posts => :foobar do
78 attributes :id, :title
79 end
80
2b1b46f @nesquena Improve readme docs
authored
81 ### Glued Attributes ###
82
83 You can also append attributes to the root node:
84
85 glue @post do
86 attributes :id => :post_id, :name => :post_name
87 end
88
89 Use glue to add additional attributes to the parent object.
90
91 ### Custom Nodes ###
92
93 This will generate a json response with the attributes specified. You can also include arbitrary code:
94
95 # app/views/users/show.json.rabl
96 code :full_name do |u|
97 u.first_name + " " + u.last_name
98 end
99
100 You can use custom "code" nodes to create flexible representations of a value utilizing data from the model.
101
da37d89 @nesquena Adds sub sections for features
authored
102 ### Partials ###
2b1b46f @nesquena Improve readme docs
authored
103
104 Often you need to access sub-objects in order to construct your own custom nodes for more complex associations. You can get access to the hash representation of another object:
3951fb7 @nesquena Updates and prepare for initial release
authored
105
106 code :location do
2b1b46f @nesquena Improve readme docs
authored
107 { :city => @city, :address => partial("web/users/address", :object => @address) }
3951fb7 @nesquena Updates and prepare for initial release
authored
108 end
109
2b1b46f @nesquena Improve readme docs
authored
110 or an object associated to the parent model:
3951fb7 @nesquena Updates and prepare for initial release
authored
111
2b1b46f @nesquena Improve readme docs
authored
112 code :location do |m|
113 { :city => m.city, :address => partial("web/users/address", :object => m.address) }
3951fb7 @nesquena Updates and prepare for initial release
authored
114 end
115
2b1b46f @nesquena Improve readme docs
authored
116 You can use these to construct arbitrarily complex nodes for APIs.
117
da37d89 @nesquena Adds sub sections for features
authored
118 ### Inheritance ###
2b1b46f @nesquena Improve readme docs
authored
119
120 Another common limitation of many json builders is code redundancy. Typically every representation of an object across endpoints share common attributes or nodes. The nodes for a 'post' object are probably the same or similar in most references throughout the various endpoints.
121
122 RABL has the ability to extend other "base" rabl templates and additional attributes:
3951fb7 @nesquena Updates and prepare for initial release
authored
123
2b1b46f @nesquena Improve readme docs
authored
124 # app/views/users/advanced.json.rabl
125 extends "users/base" # another RABL template in "app/views/users/base.json.rabl"
3951fb7 @nesquena Updates and prepare for initial release
authored
126
2b1b46f @nesquena Improve readme docs
authored
127 code :can_drink do |m|
128 m.age > 21
3951fb7 @nesquena Updates and prepare for initial release
authored
129 end
130
2b1b46f @nesquena Improve readme docs
authored
131 You can also extend other rabl templates in constructing nodes to reduce duplication:
61d9f8d @nesquena Cleanup readme order
authored
132
133 # app/views/users/show.json.rabl
134 child @address do
135 extends "address/item"
136 end
137
2b1b46f @nesquena Improve readme docs
authored
138 Using partials and inheritance can significantly reduce code duplication in your templates.
61d9f8d @nesquena Cleanup readme order
authored
139
3951fb7 @nesquena Updates and prepare for initial release
authored
140 ## Issues ##
eec7acb @nesquena Initial commit to rabl
authored
141
3951fb7 @nesquena Updates and prepare for initial release
authored
142 * I am sloppy and once again failed to unit test this. Don't use it in production until I do obviously.
Something went wrong with that request. Please try again.