Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 314 lines (217 sloc) 8.313 kB
89df60b @gazay Initial commit
authored
1 # Gon gem — get your Rails variables in your js
e133e45 @gazay Typo
authored
2
926ab15 @gazay small logo
authored
3 ![Gon. You should try this. If you look closer - you will see an elephant.](https://github.com/gazay/gon/raw/master/doc/logo_small.png)
72fe424 @gazay An elephant
authored
4
89df60b @gazay Initial commit
authored
5
ed329e5 Typo
Jim Remsik authored
6 If you need to send some data to your js files and you don't want to do this with long way through views and parsing - use this force!
89df60b @gazay Initial commit
authored
7
82c6053 @gazay Bump version
authored
8 Now with [Jbuilder](https://github.com/rails/jbuilder) and [Rabl](https://github.com/nesquena/rabl) support!
e133e45 @gazay Typo
authored
9
3104d77 @gazay Link to gon-sinatra
authored
10 For Sinatra available [gon-sinatra](https://github.com/gazay/gon-sinatra).
11
6e5f5a2 @gazay Explanation of usage in JS
authored
12 ## An example of typical use
88e28a3 @gazay Readme and version now 2.0.0
authored
13
22e1210 @gazay Bump version after pull request commits
authored
14 ### Very good and detailed example and reasons to use is considered in [railscast](http://railscasts.com/episodes/324-passing-data-to-javascript) by Ryan Bates
15
88e28a3 @gazay Readme and version now 2.0.0
authored
16 When you need to send some start data from your controller to your js
6e5f5a2 @gazay Explanation of usage in JS
authored
17 you might be doing something like this:
88e28a3 @gazay Readme and version now 2.0.0
authored
18
6e5f5a2 @gazay Explanation of usage in JS
authored
19 1. Write this data in controller(presenter/model) to some variable
20 2. In view for this action you put this variable to some objects by data
edd238f @gazay Readme %#$%
authored
21 attributes, or write js right in view
6e5f5a2 @gazay Explanation of usage in JS
authored
22 3. Then there can be two ways in js:
23 + if you previously wrote data in data
edd238f @gazay Readme %#$%
authored
24 attributes - you should parse this attributes and write data to some
6e5f5a2 @gazay Explanation of usage in JS
authored
25 js variable.
26 + if you wrote js right in view (many frontenders would shame you for
edd238f @gazay Readme %#$%
authored
27 that) - you just use data from this js - OK.
28 4. You can use your data in your js
88e28a3 @gazay Readme and version now 2.0.0
authored
29
6e5f5a2 @gazay Explanation of usage in JS
authored
30 And everytime when you need to send some data from action to js you do this.
88e28a3 @gazay Readme and version now 2.0.0
authored
31
32 With gon you configure it firstly - just put in layout one tag, and add
6e5f5a2 @gazay Explanation of usage in JS
authored
33 gem line to your Gemfile and do the following:
34
35 1. Write variables by
36
37 ``` ruby
38 gon.variable_name = variable_value
39 ```
40
41 2. In your js you get this by
42
43 ``` js
44 gon.variable_name
45 ```
88e28a3 @gazay Readme and version now 2.0.0
authored
46
edd238f @gazay Readme %#$%
authored
47 3. profit?
88e28a3 @gazay Readme and version now 2.0.0
authored
48
89df60b @gazay Initial commit
authored
49 ## Usage
50
020007b @gazay Added description and usage
authored
51 `app/views/layouts/application.html.erb`
52
53 ``` erb
54 <head>
55 <title>some title</title>
83b22e3 @gazay Js generation
authored
56 <%= include_gon %>
57 <!-- include your action js code -->
020007b @gazay Added description and usage
authored
58 ...
59 ```
60
c165afc @dnagir minor spelling fixes in README
dnagir authored
61 To camelize your variables in js you can use:
dd4e7e3 @gazay Now you can use camelized variables in your JS
authored
62
63 ``` erb
64 <head>
65 <title>some title</title>
66 <%= include_gon(:camel_case => true) %>
67 <!-- include your action js code with camelized variables -->
68 ...
69 ```
70
c165afc @dnagir minor spelling fixes in README
dnagir authored
71 You can change the namespace of the variables:
d55978f @gazay Added custom namespacing for js gon
authored
72
73 ``` erb
74 <head>
75 <title>some title</title>
76 <%= include_gon(:namespace => 'serverExports') %>
77 <!-- include your action js code with 'serverExports' namespace -->
78 ...
79 ```
80
c165afc @dnagir minor spelling fixes in README
dnagir authored
81 You put something like this in the action of your controller:
020007b @gazay Added description and usage
authored
82
83 ``` ruby
a4f0807 @gazay Added types to description
authored
84 @your_int = 123
85 @your_array = [1,2]
86 @your_hash = {'a' => 1, 'b' => 2}
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
87 gon.your_int = @your_int
88 gon.your_other_int = 345 + gon.your_int
89 gon.your_array = @your_array
90 gon.your_array << gon.your_int
91 gon.your_hash = @your_hash
7287e85 @gazay Bump version to 1.0.0
authored
92
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
93 gon.all_variables # > {:your_int => 123, :your_other_int => 468, :your_array => [1, 2, 123], :your_hash => {'a' => 1, 'b' => 2}}
94 gon.your_array # > [1, 2, 123]
7287e85 @gazay Bump version to 1.0.0
authored
95
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
96 gon.clear # gon.all_variables now is {}
020007b @gazay Added description and usage
authored
97 ```
98
c165afc @dnagir minor spelling fixes in README
dnagir authored
99 Access the varaibles from your JavaScript file:
020007b @gazay Added description and usage
authored
100
101 ``` js
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
102 alert(gon.your_int)
103 alert(gon.your_other_int)
104 alert(gon.your_array)
105 alert(gon.your_hash)
020007b @gazay Added description and usage
authored
106 ```
89df60b @gazay Initial commit
authored
107
dd4e7e3 @gazay Now you can use camelized variables in your JS
authored
108 With camelize:
109
110 ``` js
111 alert(gon.yourInt)
112 alert(gon.yourOtherInt)
113 alert(gon.yourArray)
114 alert(gon.yourHash)
115 ```
116
d55978f @gazay Added custom namespacing for js gon
authored
117 With custom namespace and camelize:
118
119 ``` js
120 alert(customNamespace.yourInt)
121 alert(customNamespace.yourOtherInt)
122 alert(customNamespace.yourArray)
123 alert(customNamespace.yourHash)
124 ```
125
88e28a3 @gazay Readme and version now 2.0.0
authored
126 ## Usage with Rabl
127
6e5f5a2 @gazay Explanation of usage in JS
authored
128 Now you can write your variables assign logic to templates with [Rabl](https://github.com/nesquena/rabl).
129 The way of writing Rabl templates is very clearly described in their repo.
88e28a3 @gazay Readme and version now 2.0.0
authored
130
847a63d @Bushjumper Remove RABL dependency [Issue 19]
Bushjumper authored
131 Add Rabl to your Gemfile
132
133 `Gemfile`
134
135 ``` ruby
136 gem 'rabl'
137 ```
138
88e28a3 @gazay Readme and version now 2.0.0
authored
139 Profit of using Rabl with gon:
edd238f @gazay Readme %#$%
authored
140
141 1. You can clean your controllers now!
c165afc @dnagir minor spelling fixes in README
dnagir authored
142 2. Work with database objects and collections clearly and easyly
edd238f @gazay Readme %#$%
authored
143 3. All power of Rabl
6e5f5a2 @gazay Explanation of usage in JS
authored
144 4. You can still be lazy and don't use common way to transfer data in js
edd238f @gazay Readme %#$%
authored
145 5. And so on
88e28a3 @gazay Readme and version now 2.0.0
authored
146
147 For using gon with Rabl you need to create new Rabl template and map gon
148 to it.
149 For example you have model Post with attributes :title and :body.
150 You want to get all your posts in your js as an Array.
6e5f5a2 @gazay Explanation of usage in JS
authored
151 That's what you need to do:
88e28a3 @gazay Readme and version now 2.0.0
authored
152
6e5f5a2 @gazay Explanation of usage in JS
authored
153 1. Create Rabl template. I prefer creating special directory for
edd238f @gazay Readme %#$%
authored
154 templates which are not view templates.
88e28a3 @gazay Readme and version now 2.0.0
authored
155
edd238f @gazay Readme %#$%
authored
156 `app/goners/posts/index.rabl`
88e28a3 @gazay Readme and version now 2.0.0
authored
157
edd238f @gazay Readme %#$%
authored
158 ``` rabl
159 collection @posts => 'posts'
160 attributes :id, :title, :body
161 ```
88e28a3 @gazay Readme and version now 2.0.0
authored
162
6e5f5a2 @gazay Explanation of usage in JS
authored
163 2. All you need to do after that is only to map this template to gon.
88e28a3 @gazay Readme and version now 2.0.0
authored
164
edd238f @gazay Readme %#$%
authored
165 `app/controllers/post_controller.rb#index`
88e28a3 @gazay Readme and version now 2.0.0
authored
166
edd238f @gazay Readme %#$%
authored
167 ``` ruby
168 def index
169 # some controller logic
170 @posts = Post.all # Rabl works with instance variables of controller
88e28a3 @gazay Readme and version now 2.0.0
authored
171
edd238f @gazay Readme %#$%
authored
172 gon.rabl 'app/goners/posts/index.rabl'
6e5f5a2 @gazay Explanation of usage in JS
authored
173 # some controller logic
edd238f @gazay Readme %#$%
authored
174 end
175 ```
88e28a3 @gazay Readme and version now 2.0.0
authored
176
6e5f5a2 @gazay Explanation of usage in JS
authored
177 Thats it! Now you will get in your js gon.posts variable which is Array of
edd238f @gazay Readme %#$%
authored
178 post objects with attributes :id, :title and :body.
88e28a3 @gazay Readme and version now 2.0.0
authored
179
6e5f5a2 @gazay Explanation of usage in JS
authored
180 In javascript file for view of this action write call to your variable:
181
182 ``` js
183 alert(gon.posts)
184 alert(gon.posts[0])
185 alert(gon.posts[0].post.body)
186 ```
187
fea6c85 @gazay Typo
authored
188 P.s. If you didn't put include_gon tag in your html head area - it
189 wouldn't work. You can read about this in common usage above.
88e28a3 @gazay Readme and version now 2.0.0
authored
190
191 ### Some tips of usage Rabl with gon:
192
193 If you don't use alias in Rabl template:
194
195 ``` rabl
196 collection @posts
197 ....
198 ```
199
200 instead of using that:
201
202 ``` rabl
203 collection @posts => 'alias'
204 ....
205 ```
206
6e5f5a2 @gazay Explanation of usage in JS
authored
207 Rabl will return you an array and gon by default will put it to variable
88e28a3 @gazay Readme and version now 2.0.0
authored
208 gon.rabl
209
6e5f5a2 @gazay Explanation of usage in JS
authored
210 Two ways how you can change it - using aliases or you can add alias to
88e28a3 @gazay Readme and version now 2.0.0
authored
211 gon mapping method:
212
213 ``` ruby
214 # your controller stuff here
215
216 gon.rabl 'path/to/rabl/file', :as => 'alias'
217 ```
218
82c6053 @gazay Bump version
authored
219 ## Usage with Jbuilder
220
221 Use gon with [Jbuilder](https://github.com/rails/jbuilder) as with [Rabl](https://guthub.com/nesquena/rabl):
222
223 Jbuilder works now only on Ruby 1.9+, so Gon support for Jbuilder works on 1.9+ only
224
fdff33b @gazay Readme and version
authored
225 0. Add jbuilder to your Gemfile (because of it depends on
226 ActiveSuppurt '~> 3.0.0')
227
228 `Gemfile`
229
230 ``` ruby
231 gem 'jbuilder'
232 ```
233
82c6053 @gazay Bump version
authored
234 1. Create Jbuilder template.
235
236 `app/views/posts/index.json.jbuilder`
237
238 ``` jbuilder
239 json.posts @posts, :id, :title, :body
240 ```
241
242 2. In your controller you should map this template to gon.
243
244 ``` ruby
245 def index
246 # some controller logic
247 @posts = Post.all
248
249 gon.jbuilder 'app/views/posts/index.json.jbuilder'
250 # some controller logic
251 end
252 ```
fdff33b @gazay Readme and version
authored
253
82c6053 @gazay Bump version
authored
254 In javascript file for view of this action write call to your variable:
255
fdff33b @gazay Readme and version
authored
256 Now you can use partials in jbuilder:
257
258 `app/views/posts/index.json.jbuilder`
259
260 ``` jbuilder
261 json.partial! 'app/views/posts/_part.json.jbuilder', :comments => @posts[0].comments
262 ```
263
264 `app/views/posts/_part.json.jbuilder`
265
266 ``` jbuilder
267 json.comments comments.map{ |it| 'comment#' + it.id }
268 ```
269
82c6053 @gazay Bump version
authored
270 ``` js
271 alert(gon.posts)
272 alert(gon.posts[0])
273 alert(gon.posts[0].post.body)
fdff33b @gazay Readme and version
authored
274 alert(gon.comments)
275 alert(gon.comments[0])
82c6053 @gazay Bump version
authored
276 ```
277
278 P.s. If you didn't put include_gon tag in your html head area - it
279 wouldn't work. You can read about this in common usage above.
280
89df60b @gazay Initial commit
authored
281 ## Installation
282
283 Puts this line into `Gemfile` then run `$ bundle`:
284
285 ``` ruby
42b2d35 @gazay Bump version to version without blanksate dependency
authored
286 gem 'gon', '2.0.6'
89df60b @gazay Initial commit
authored
287 ```
288
289 Or if you are old-school Rails 2 developer put this into `config/environment.rb` and run `$ rake gems:install`:
290
291 ``` ruby
42b2d35 @gazay Bump version to version without blanksate dependency
authored
292 config.gem 'gon', :version => '2.0.6'
89df60b @gazay Initial commit
authored
293 ```
294
da310ad @gazay Edited README.md via GitHub
authored
295 Or manually install gon gem: `$ gem install gon`
89df60b @gazay Initial commit
authored
296
297 ## Contributors
298
299 * @gazay
300
2f1bc0e @gazay Edited README.md via GitHub
authored
301 Special thanks to @brainopia, @kossnocorp and @ai.
89df60b @gazay Initial commit
authored
302
303 ## License
304
305 The MIT License
306
ccc3ecf @gazay Copyright update
authored
307 Copyright (c) 2011-2012 gazay
89df60b @gazay Initial commit
authored
308
309 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
310
311 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
312
313 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.