Skip to content

HTTPS clone URL

Subversion checkout URL

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