Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 240 lines (166 sloc) 6.999 kb
89df60b @gazay Initial commit
authored
1 # Gon gem — get your Rails variables in your js
e133e45 @gazay Typo
authored
2
874607a @gitter-badger Added Gitter badge
gitter-badger authored
3 [![Join the chat at https://gitter.im/gazay/gon](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/gazay/gon?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
4
926ab15 @gazay small logo
authored
5 ![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
6
472fce4 @gazay Couple fixes in README
authored
7 [![Build Status](https://secure.travis-ci.org/gazay/gon.png)](http://travis-ci.org/gazay/gon) [![CodeClimate](https://codeclimate.com/github/gazay/gon/badges/gpa.svg)](https://codeclimate.com/github/gazay/gon)
731657e @gazay Add travis-ci img
authored
8
ed329e5 Typo
Jim Remsik authored
9 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
10
3f4d521 @gazay Readme
authored
11 Now you can easily renew data in your variables through ajax with [gon.watch](https://github.com/gazay/gon/wiki/Usage-gon-watch)!
12
8699217 @jtherrell Updated README. Includes gon.rabl with rabl-rails usage details.
jtherrell authored
13 With [Jbuilder](https://github.com/rails/jbuilder), [Rabl](https://github.com/nesquena/rabl), and [Rabl-Rails](https://github.com/ccocchi/rabl-rails) support!
e133e45 @gazay Typo
authored
14
3104d77 @gazay Link to gon-sinatra
authored
15 For Sinatra available [gon-sinatra](https://github.com/gazay/gon-sinatra).
16
24ea60a @gazay Link for .Net port of Gon
authored
17 For .Net MVC available port [NGon](https://github.com/brooklynDev/NGon).
18
5aabd04 @gazay Add martians banner
authored
19 <a href="https://evilmartians.com/?utm_source=gon">
20 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
21 </a>
22
6e5f5a2 @gazay Explanation of usage in JS
authored
23 ## An example of typical use
88e28a3 @gazay Readme and version now 2.0.0
authored
24
22e1210 @gazay Bump version after pull request commits
authored
25 ### 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
26
88e28a3 @gazay Readme and version now 2.0.0
authored
27 When you need to send some start data from your controller to your js
6e5f5a2 @gazay Explanation of usage in JS
authored
28 you might be doing something like this:
88e28a3 @gazay Readme and version now 2.0.0
authored
29
6e5f5a2 @gazay Explanation of usage in JS
authored
30 1. Write this data in controller(presenter/model) to some variable
31 2. In view for this action you put this variable to some objects by data
edd238f @gazay Readme %#$%
authored
32 attributes, or write js right in view
6e5f5a2 @gazay Explanation of usage in JS
authored
33 3. Then there can be two ways in js:
34 + if you previously wrote data in data
edd238f @gazay Readme %#$%
authored
35 attributes - you should parse this attributes and write data to some
31167a5 @joshuapinter Fixed list markdown.
joshuapinter authored
36 js variable.
6e5f5a2 @gazay Explanation of usage in JS
authored
37 + if you wrote js right in view (many frontenders would shame you for
edd238f @gazay Readme %#$%
authored
38 that) - you just use data from this js - OK.
39 4. You can use your data in your js
88e28a3 @gazay Readme and version now 2.0.0
authored
40
6e5f5a2 @gazay Explanation of usage in JS
authored
41 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
42
43 With gon you configure it firstly - just put in layout one tag, and add
6e5f5a2 @gazay Explanation of usage in JS
authored
44 gem line to your Gemfile and do the following:
45
46 1. Write variables by
47
48 ``` ruby
49 gon.variable_name = variable_value
7e7cdc9 Update README.md
Arsen Gasparyan authored
50
3079ce0 Update README.md, again
Arsen Gasparyan authored
51 # or new syntax
52 gon.push({
dfebdb9 Gon push syntax, use any object
Arsen Gasparyan authored
53 :user_id => 1,
54 :user_role => "admin"
3079ce0 Update README.md, again
Arsen Gasparyan authored
55 })
dfebdb9 Gon push syntax, use any object
Arsen Gasparyan authored
56
57 gon.push(any_object) # any_object with respond_to? :each_pair
6e5f5a2 @gazay Explanation of usage in JS
authored
58 ```
59
60 2. In your js you get this by
61
62 ``` js
63 gon.variable_name
64 ```
88e28a3 @gazay Readme and version now 2.0.0
authored
65
edd238f @gazay Readme %#$%
authored
66 3. profit?
88e28a3 @gazay Readme and version now 2.0.0
authored
67
48e6d74 @Silex Remove include_gon(watch: true) from README
Silex authored
68 With the `gon.watch` feature you can easily renew data in gon variables!
69 Simply call `gon.watch` from your js file. It's super useful
70 in modern web applications!
3f4d521 @gazay Readme
authored
71
89df60b @gazay Initial commit
authored
72 ## Usage
73
6be3879 @gazay New readme, all detailed info in wiki now.
authored
74 ### More details about configuration and usage you can find in [gon wiki](https://github.com/gazay/gon/wiki)
020007b @gazay Added description and usage
authored
75
6be3879 @gazay New readme, all detailed info in wiki now.
authored
76 Old readme available in [./README_old.md](https://github.com/gazay/gon/blob/master/README_old.md)
020007b @gazay Added description and usage
authored
77
dd4e7e3 @gazay Now you can use camelized variables in your JS
authored
78
6be3879 @gazay New readme, all detailed info in wiki now.
authored
79 `app/views/layouts/application.html.erb`
9d34903 @torbjon added type text/javascript option
torbjon authored
80
81 ``` erb
82 <head>
83 <title>some title</title>
6be3879 @gazay New readme, all detailed info in wiki now.
authored
84 <%= include_gon %>
85 <!-- include your action js code -->
9d34903 @torbjon added type text/javascript option
torbjon authored
86 ...
87 ```
88
26185fd @mohsinali Update README.md
mohsinali authored
89 For rails 4:
90 ``` erb
91 <%= Gon::Base.render_data({}) %>
92 ...
93 ```
94
95
96
6be3879 @gazay New readme, all detailed info in wiki now.
authored
97 You can pass some [options](https://github.com/gazay/gon/wiki/Options)
98 to `include_gon` method.
725e14d @gazay Added need_tag option. Kudos to @afa
authored
99
c165afc @dnagir minor spelling fixes in README
dnagir authored
100 You put something like this in the action of your controller:
020007b @gazay Added description and usage
authored
101
102 ``` ruby
a4f0807 @gazay Added types to description
authored
103 @your_int = 123
104 @your_array = [1,2]
105 @your_hash = {'a' => 1, 'b' => 2}
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
106 gon.your_int = @your_int
107 gon.your_other_int = 345 + gon.your_int
108 gon.your_array = @your_array
109 gon.your_array << gon.your_int
110 gon.your_hash = @your_hash
7287e85 @gazay Bump version to 1.0.0
authored
111
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
112 gon.all_variables # > {:your_int => 123, :your_other_int => 468, :your_array => [1, 2, 123], :your_hash => {'a' => 1, 'b' => 2}}
113 gon.your_array # > [1, 2, 123]
7287e85 @gazay Bump version to 1.0.0
authored
114
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
115 gon.clear # gon.all_variables now is {}
020007b @gazay Added description and usage
authored
116 ```
117
714c249 @bbasata Fix spelling in README
bbasata authored
118 Access the variables from your JavaScript file:
020007b @gazay Added description and usage
authored
119
120 ``` js
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
121 alert(gon.your_int)
122 alert(gon.your_other_int)
123 alert(gon.your_array)
124 alert(gon.your_hash)
020007b @gazay Added description and usage
authored
125 ```
89df60b @gazay Initial commit
authored
126
881dd64 @vijoc Update Readme to introduce include_gon_amd
vijoc authored
127 ### AMD compatible version: `include_gon_amd`
128
5aabd04 @gazay Add martians banner
authored
129 If your site uses AMD modules you can use the `include_gon_amd` helper to
130 include the variables and watch function as a module. Options are mostly
131 the same as for `include_gon`, except for `namespace_check`, which does
132 nothing and `namespace`, which is used as the name of the defined module.
881dd64 @vijoc Update Readme to introduce include_gon_amd
vijoc authored
133 The end result will look somewhat like the following:
134
135 ```js
136 define('yourNameSpace', [], function() {
137 var gon = {};
138 gon.yourVariable = yourValue;
139 // etc...
140
141 return gon;
142 });
143 ```
144
145 A (very) simplified usage example:
146
147 `app/views/layouts/application.html.erb`
148
149 ```ruby
150 include_gon_amd namespace: 'data'
151 ```
152
153 `Some JavaScript module`
154
155 ```js
156 define(['data'], function(data) {
157 alert(data.myVariable);
158 });
159 ```
160
3f4d521 @gazay Readme
authored
161 ## gon.watch - renew your data easily!
162
163 You can use gon for renewing your data without reloading pages and
48e6d74 @Silex Remove include_gon(watch: true) from README
Silex authored
164 writing long js functions! It's really great for some live values.
3f4d521 @gazay Readme
authored
165
166 Supports `gon.watch.rabl` and `gon.watch.jbuilder` usage.
167
168 [Instruction](https://github.com/gazay/gon/wiki/Usage-gon-watch) for
169 usage gon.watch.
170
88e28a3 @gazay Readme and version now 2.0.0
authored
171 ## Usage with Rabl
172
0a349f0 @gazay Added changelog and bumped version to 3.0.0
authored
173 You can write your variables assign logic to templates with [Rabl](https://github.com/nesquena/rabl).
6e5f5a2 @gazay Explanation of usage in JS
authored
174 The way of writing Rabl templates is very clearly described in their repo.
88e28a3 @gazay Readme and version now 2.0.0
authored
175
176 Profit of using Rabl with gon:
edd238f @gazay Readme %#$%
authored
177
178 1. You can clean your controllers now!
c165afc @dnagir minor spelling fixes in README
dnagir authored
179 2. Work with database objects and collections clearly and easyly
edd238f @gazay Readme %#$%
authored
180 3. All power of Rabl
6e5f5a2 @gazay Explanation of usage in JS
authored
181 4. You can still be lazy and don't use common way to transfer data in js
edd238f @gazay Readme %#$%
authored
182 5. And so on
88e28a3 @gazay Readme and version now 2.0.0
authored
183
6be3879 @gazay New readme, all detailed info in wiki now.
authored
184 [Instruction](https://github.com/gazay/gon/wiki/Usage-with-rabl) for
185 usage gon with Rabl.
88e28a3 @gazay Readme and version now 2.0.0
authored
186
8699217 @jtherrell Updated README. Includes gon.rabl with rabl-rails usage details.
jtherrell authored
187 ## Usage with Rabl-Rails
188 `gon.rabl` works with [rabl-rails](https://github.com/ccocchi/rabl-rails). Learn to write RABL the rabl-rails way [here](https://github.com/ccocchi/rabl-rails).
189
190 Add gon and rabl-rails to your environment:
191 ```ruby
192 gem 'gon'
193 gem 'rabl-rails'
194 ```
195 Define a rabl template using rabl-rails syntax:
196 ```rabl
197 #app/views/users/show.rabl
198 object :@user
199 attributes :id, :name, :email, :location
200 ```
201 Call gon.rabl in your controller
202
203 ```ruby
204 #app/controllers/users_controller.rb
205 def show
206 @user = User.find(params[:id])
207 gon.rabl
208 end
209 ```
210
82c6053 @gazay Bump version
authored
211 ## Usage with Jbuilder
212
213 Use gon with [Jbuilder](https://github.com/rails/jbuilder) as with [Rabl](https://guthub.com/nesquena/rabl):
214
6be3879 @gazay New readme, all detailed info in wiki now.
authored
215 [Instruction](https://github.com/gazay/gon/wiki/Usage-with-jbuilder) for
216 usage gon with Jbuilder.
82c6053 @gazay Bump version
authored
217
0a349f0 @gazay Added changelog and bumped version to 3.0.0
authored
218 ## gon.global
219
6be3879 @gazay New readme, all detailed info in wiki now.
authored
220 You can use gon for sending your data to js from anywhere! It's really
221 great for some init data.
89df60b @gazay Initial commit
authored
222
6be3879 @gazay New readme, all detailed info in wiki now.
authored
223 [Instruction](https://github.com/gazay/gon/wiki/Usage-gon-global) for
224 usage gon.global.
89df60b @gazay Initial commit
authored
225
8b3b605 @Strech Added MultiJson support
Strech authored
226 ## Speed up Gon
227
228 You can use any [JSON Engine](https://github.com/intridea/multi_json#supported-json-engines) you want.
229 Gon uses `MultiJson` with autodetect mode, so all you need is just require your JSON library.
230
89df60b @gazay Initial commit
authored
231 ## Contributors
232
233 * @gazay
234
2f1bc0e @gazay Edited README.md via GitHub
authored
235 Special thanks to @brainopia, @kossnocorp and @ai.
89df60b @gazay Initial commit
authored
236
237 ## License
238
239 The MIT License
Something went wrong with that request. Please try again.