Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 238 lines (166 sloc) 6.906 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 `app/views/layouts/application.html.erb`
9d34903 @torbjon added type text/javascript option
torbjon authored
77
78 ``` erb
79 <head>
80 <title>some title</title>
6be3879 @gazay New readme, all detailed info in wiki now.
authored
81 <%= include_gon %>
82 <!-- include your action js code -->
9d34903 @torbjon added type text/javascript option
torbjon authored
83 ...
84 ```
85
26185fd @mohsinali Update README.md
mohsinali authored
86 For rails 4:
87 ``` erb
1394b4e @kirs Simplify rendering API
kirs authored
88 <%= Gon::Base.render_data %>
26185fd @mohsinali Update README.md
mohsinali authored
89 ...
90 ```
91
92
93
6be3879 @gazay New readme, all detailed info in wiki now.
authored
94 You can pass some [options](https://github.com/gazay/gon/wiki/Options)
95 to `include_gon` method.
725e14d @gazay Added need_tag option. Kudos to @afa
authored
96
c165afc @dnagir minor spelling fixes in README
dnagir authored
97 You put something like this in the action of your controller:
020007b @gazay Added description and usage
authored
98
99 ``` ruby
a4f0807 @gazay Added types to description
authored
100 @your_int = 123
101 @your_array = [1,2]
102 @your_hash = {'a' => 1, 'b' => 2}
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
103 gon.your_int = @your_int
104 gon.your_other_int = 345 + gon.your_int
105 gon.your_array = @your_array
106 gon.your_array << gon.your_int
107 gon.your_hash = @your_hash
7287e85 @gazay Bump version to 1.0.0
authored
108
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
109 gon.all_variables # > {:your_int => 123, :your_other_int => 468, :your_array => [1, 2, 123], :your_hash => {'a' => 1, 'b' => 2}}
110 gon.your_array # > [1, 2, 123]
7287e85 @gazay Bump version to 1.0.0
authored
111
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
112 gon.clear # gon.all_variables now is {}
020007b @gazay Added description and usage
authored
113 ```
114
714c249 @bbasata Fix spelling in README
bbasata authored
115 Access the variables from your JavaScript file:
020007b @gazay Added description and usage
authored
116
117 ``` js
9feb32b @gazay Bump version to 1.1.0 - this... is... STABLE!!!
authored
118 alert(gon.your_int)
119 alert(gon.your_other_int)
120 alert(gon.your_array)
121 alert(gon.your_hash)
020007b @gazay Added description and usage
authored
122 ```
89df60b @gazay Initial commit
authored
123
881dd64 @vijoc Update Readme to introduce include_gon_amd
vijoc authored
124 ### AMD compatible version: `include_gon_amd`
125
5aabd04 @gazay Add martians banner
authored
126 If your site uses AMD modules you can use the `include_gon_amd` helper to
127 include the variables and watch function as a module. Options are mostly
128 the same as for `include_gon`, except for `namespace_check`, which does
129 nothing and `namespace`, which is used as the name of the defined module.
881dd64 @vijoc Update Readme to introduce include_gon_amd
vijoc authored
130 The end result will look somewhat like the following:
131
132 ```js
133 define('yourNameSpace', [], function() {
134 var gon = {};
135 gon.yourVariable = yourValue;
136 // etc...
137
138 return gon;
139 });
140 ```
141
142 A (very) simplified usage example:
143
144 `app/views/layouts/application.html.erb`
145
146 ```ruby
147 include_gon_amd namespace: 'data'
148 ```
149
150 `Some JavaScript module`
151
152 ```js
153 define(['data'], function(data) {
154 alert(data.myVariable);
155 });
156 ```
157
3f4d521 @gazay Readme
authored
158 ## gon.watch - renew your data easily!
159
160 You can use gon for renewing your data without reloading pages and
48e6d74 @Silex Remove include_gon(watch: true) from README
Silex authored
161 writing long js functions! It's really great for some live values.
3f4d521 @gazay Readme
authored
162
163 Supports `gon.watch.rabl` and `gon.watch.jbuilder` usage.
164
165 [Instruction](https://github.com/gazay/gon/wiki/Usage-gon-watch) for
166 usage gon.watch.
167
88e28a3 @gazay Readme and version now 2.0.0
authored
168 ## Usage with Rabl
169
0a349f0 @gazay Added changelog and bumped version to 3.0.0
authored
170 You can write your variables assign logic to templates with [Rabl](https://github.com/nesquena/rabl).
6e5f5a2 @gazay Explanation of usage in JS
authored
171 The way of writing Rabl templates is very clearly described in their repo.
88e28a3 @gazay Readme and version now 2.0.0
authored
172
173 Profit of using Rabl with gon:
edd238f @gazay Readme %#$%
authored
174
175 1. You can clean your controllers now!
c165afc @dnagir minor spelling fixes in README
dnagir authored
176 2. Work with database objects and collections clearly and easyly
edd238f @gazay Readme %#$%
authored
177 3. All power of Rabl
6e5f5a2 @gazay Explanation of usage in JS
authored
178 4. You can still be lazy and don't use common way to transfer data in js
edd238f @gazay Readme %#$%
authored
179 5. And so on
88e28a3 @gazay Readme and version now 2.0.0
authored
180
6be3879 @gazay New readme, all detailed info in wiki now.
authored
181 [Instruction](https://github.com/gazay/gon/wiki/Usage-with-rabl) for
182 usage gon with Rabl.
88e28a3 @gazay Readme and version now 2.0.0
authored
183
8699217 @jtherrell Updated README. Includes gon.rabl with rabl-rails usage details.
jtherrell authored
184 ## Usage with Rabl-Rails
185 `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).
186
187 Add gon and rabl-rails to your environment:
188 ```ruby
189 gem 'gon'
190 gem 'rabl-rails'
191 ```
192 Define a rabl template using rabl-rails syntax:
193 ```rabl
194 #app/views/users/show.rabl
195 object :@user
196 attributes :id, :name, :email, :location
197 ```
198 Call gon.rabl in your controller
199
200 ```ruby
201 #app/controllers/users_controller.rb
202 def show
203 @user = User.find(params[:id])
204 gon.rabl
205 end
206 ```
207
82c6053 @gazay Bump version
authored
208 ## Usage with Jbuilder
209
210 Use gon with [Jbuilder](https://github.com/rails/jbuilder) as with [Rabl](https://guthub.com/nesquena/rabl):
211
6be3879 @gazay New readme, all detailed info in wiki now.
authored
212 [Instruction](https://github.com/gazay/gon/wiki/Usage-with-jbuilder) for
213 usage gon with Jbuilder.
82c6053 @gazay Bump version
authored
214
0a349f0 @gazay Added changelog and bumped version to 3.0.0
authored
215 ## gon.global
216
6be3879 @gazay New readme, all detailed info in wiki now.
authored
217 You can use gon for sending your data to js from anywhere! It's really
218 great for some init data.
89df60b @gazay Initial commit
authored
219
6be3879 @gazay New readme, all detailed info in wiki now.
authored
220 [Instruction](https://github.com/gazay/gon/wiki/Usage-gon-global) for
221 usage gon.global.
89df60b @gazay Initial commit
authored
222
8b3b605 @Strech Added MultiJson support
Strech authored
223 ## Speed up Gon
224
225 You can use any [JSON Engine](https://github.com/intridea/multi_json#supported-json-engines) you want.
226 Gon uses `MultiJson` with autodetect mode, so all you need is just require your JSON library.
227
89df60b @gazay Initial commit
authored
228 ## Contributors
229
230 * @gazay
d029508 @gazay Add @takiy33 as contributor
authored
231 * @takiy33
89df60b @gazay Initial commit
authored
232
2f1bc0e @gazay Edited README.md via GitHub
authored
233 Special thanks to @brainopia, @kossnocorp and @ai.
89df60b @gazay Initial commit
authored
234
235 ## License
236
237 The MIT License
Something went wrong with that request. Please try again.