Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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