Skip to content

HTTPS clone URL

Subversion checkout URL

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