Permalink
Browse files

Readme and version now 2.0.0

  • Loading branch information...
1 parent e3f1fe8 commit 88e28a356dff62a26729ae1bf0ec694699774eb9 @gazay committed Nov 7, 2011
Showing with 102 additions and 3 deletions.
  1. +101 −2 README.md
  2. +1 −1 lib/gon/version.rb
View
@@ -1,7 +1,31 @@
# Gon gem — get your Rails variables in your js
+## Now with [Rabl](https://github.com/nesquena/rabl) support!
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!
+## A example of typical use
+
+When you need to send some start data from your controller to your js
+you probably doing something like this:
+
+1. Write this data in controller(presenter/model) in some variable
+2. In view for this action you put this data in some objects by data
+ attributes, or write js right in view
+3. Then in js it depends - if you previously write data in data
+ attributes - you should parse this attributes and write data to some
+js variable. If you write js right in view (many frontenders shame you for
+that) - you just use data from this js - OK.
+4. You can use your data in your js
+
+And everytime when you need some data from action to js you do this.
+
+With gon you configure it firstly - just put in layout one tag, and add
+gem line to your Gemfile and do two actions:
+
+1. Write variables by gon.variable_name = variable_value
+2. In your js you get this by gon.variable_name
+3. profit?
+
## Usage
`app/views/layouts/application.html.erb`
@@ -79,18 +103,93 @@ alert(customNamespace.yourArray)
alert(customNamespace.yourHash)
```
+## Usage with Rabl
+
+Now you can write your variables assign logic in templates with [Rabl](https://github.com/nesquena/rabl).
+How write templates very clearly described in their repo.
+
+Profit of using Rabl with gon:
+1. You can clean your controllers now!
+2. Clear and easy work with database objects and collections
+3. All power of Rabl
+4. You still can be lazy and don't use common way to transfer data in js
+5. And so on
+
+For using gon with Rabl you need to create new Rabl template and map gon
+to it.
+For example you have model Post with attributes :title and :body.
+You want to get all your posts in your js as an Array.
+Thats what you need to do:
+
+1. Create Rabl template. I preffer creating special directory for
+ templates which are not view templates.
+
+`app/goners/posts/index.rabl`
+
+``` rabl
+collection @posts => 'posts'
+attributes :id, :title, :body
+```
+
+2. After that you need only map this template to gon.
+
+`app/controllers/post_controller.rb#index`
+
+``` ruby
+def index
+ # some controller logic
+ @posts = Post.all # Rabl works with instance variables of controller
+
+ gon.rabl 'app/goners/posts/index.rabl'
+end
+```
+
+Thats it! In your js now you get gon.posts variable which is Array of
+post objects with attributes :id, :title and :body.
+
+P.s. If you didn't put include_gon tag in your html head area - it
+wouldn't work. You can read about this in common usage above.
+
+### Some tips of usage Rabl with gon:
+
+If you don't use alias in Rabl template:
+
+``` rabl
+collection @posts
+....
+```
+
+instead of using that:
+
+``` rabl
+collection @posts => 'alias'
+....
+```
+
+Rabl will return you array and gon by default put it to variable
+gon.rabl
+
+Two way how you can change it - using aliases or you can add alias to
+gon mapping method:
+
+``` ruby
+# your controller stuff here
+
+gon.rabl 'path/to/rabl/file', :as => 'alias'
+```
+
## Installation
Puts this line into `Gemfile` then run `$ bundle`:
``` ruby
-gem 'gon', '1.1.3'
+gem 'gon', '2.0.0'
```
Or if you are old-school Rails 2 developer put this into `config/environment.rb` and run `$ rake gems:install`:
``` ruby
-config.gem 'gon', :version => '1.1.3'
+config.gem 'gon', :version => '2.0.0'
```
Or manually install gon gem: `$ gem install gon`
View
@@ -1,3 +1,3 @@
module Gon
- VERSION = '1.1.3'
+ VERSION = '2.0.0'
end

0 comments on commit 88e28a3

Please sign in to comment.