Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 113 lines (79 sloc) 3.358 kb
60785f1 @h3h Add README.
h3h authored
1 # Boxer
2
3 Boxer is a template engine for creating nested and multi-view JSON objects
4 from Ruby hashes.
5
a4e1c1d @h3h Update README with better links & adorable logo.
h3h authored
6 <section style="text-align:center">
7 <a href="http://engineering.gowalla.com/2011/10/24/boxer/">
8 <img src="http://engineering.gowalla.com/images/boxer.png" alt="Logo" />
9 </a>
10 </section>
11
60785f1 @h3h Add README.
h3h authored
12 ## The Problem
13
14 Say you have a couple ActiveRecord models in your Rails app and you want to
15 render an API response in JSON, but the view of each of those model objects
16 may change based on the API action that's being requested.
17
18 * User
19 * Place
20
21 For instance, the API for `GET /users/:id` should render a full representation
22 of the User object in question, including all relevant attributes.
23
24 But in your `GET /places/:id/users` API call, you only need short-form
25 representations of the users at that place, without every single attribute
26 being included in the response.
27
28 ## The Solution
29
30 Boxer allows you to define a box for each type of object you'd like to display
31 (or for each amalgamation of objects you want to display&mdash;it's up to you).
32
33 Boxer.box(:user) do |box, user|
34 {
35 :name => user.name,
36 :age => user.age,
37 }
38 end
39
40 To display different views on the same object, you can use Boxer's views:
41
42 Boxer.box(:user) do |box, user|
43 box.view(:base) do
44 {
45 :name => user.name,
46 :age => user.age,
47 }
48 end
49
50 box.view(:full, :extends => :base) do
51 {
52 :email => user.email,
53 :is_private => user.private?,
54 }
55 end
56 end
57
58 As you might guess, the `:full` view includes all attributes in the `:base`
59 view by virtue of the `:extends` option.
60
61 Now, in order to render a User with the `:base` view, simple call `Boxer.ship`:
62
63 Boxer.ship(:user, User.first)
64
65 Boxer assumes that you want the `:base` view if no view is specified to
66 `ship`&mdash;it's the only specially-named view.
67
68 To render the full view for the same user:
69
70 Boxer.ship(:user, User.first, :view => :full)
71
72 Which will give you back a Ruby hash on which you can call `#to_json`, to render
73 your JSON response<sup>1</sup>:
74
75 >> Boxer.ship(:user, User.first, :view => :full).to_json
76 => "{"name": "Bo Jim", "age": 17, "email": "b@a.com", "is_private": false}"
77
78 Composing different boxes together is as simple as calling `Boxer.ship` from
79 within a box&mdash;it's just Ruby:
80
81 Boxer.box(:place) do |box, place|
82 {
83 :name => place.name,
84 :address => place.address,
85 :top_user => Boxer.ship(:user, place.users.order(:visits).first),
86 }
87 end
88
1cf3ffc @h3h Update README.
h3h authored
89 1. `Hash#to_json` requires a [json library](http://rubygems.org/gems/json)
60785f1 @h3h Add README.
h3h authored
90
91 ## More Features
92
2dab06d @h3h Update home.
h3h authored
93 See [the wiki](/gowalla/boxer/wiki) for more features of Boxer, including:
9b6c740 @h3h Update README.
h3h authored
94
2dab06d @h3h Update home.
h3h authored
95 * [Extra Arguments](/gowalla/boxer/wiki/Extra-Arguments)
96 * [Preconditions](/gowalla/boxer/wiki/Preconditions)
97 * [Helper Methods in Boxes](/gowalla/boxer/wiki/Helper-Methods-in-Boxes)
98 * [Box Includes](/gowalla/boxer/wiki/Box-Includes)
99 * [Multiple Inheritance](/gowalla/boxer/wiki/Multiple-Inheritance)
60785f1 @h3h Add README.
h3h authored
100
a030dab @h3h Add link to gem from README.
h3h authored
101 ## Installation
102
103 Install the [boxer gem](http://rubygems.org/gems/boxer).
104
60785f1 @h3h Add README.
h3h authored
105 ## Original Author
106
2dab06d @h3h Update home.
h3h authored
107 * [Brad Fults](http://h3h.net/), [Gowalla Incorporated](http://gowalla.com/)
60785f1 @h3h Add README.
h3h authored
108
109 ## Inspiration
110
a4e1c1d @h3h Update README with better links & adorable logo.
h3h authored
111 Boxer was inspired by [RABL](https://github.com/nesquena/rabl),
112 by [Nathan Esquenazi](https://github.com/nesquena).
Something went wrong with that request. Please try again.