Skip to content

HTTPS clone URL

Subversion checkout URL

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