diff --git a/README.md b/README.md index 594c214..67527f9 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ RABL (Ruby API Builder Language) is a ruby templating system for rendering resou RABL-rails only target Rails 3+ application because Rails 2 applications are becoming less and less present and will be obsolete with Rails 4. So let's look to the future ! -So now you ask why used `rabl-rails` if `rabl` already exists and supports Rails. Rabl-rails is *faster* and uses * less memory* than standard rabl gem while letting you access same features. Of course, there are some slight changes to do on your templates to get this gem to work but it should't take you more than 5 minutes. +So now you ask why used `rabl-rails` if `rabl` already exists and supports Rails. Rabl-rails is **faster** and uses **less memory** than standard rabl gem while letting you access same features. Of course, there are some slight changes to do on your templates to get this gem to work but it should't take you more than 5 minutes. ## Installation @@ -17,7 +17,7 @@ gem install rabl-rails or add directly to your `Gemfile` ``` -gem 'rabl' +gem 'rabl-rails' ``` And that's it ! @@ -30,9 +30,9 @@ assuming you have a `Post` model filled with blog posts, and a `PostController` ```ruby class PostController < ApplicationController respond_to :html, :json, :xml - + def index - @posts = Post.order('created_at DESC') + @posts = Post.order('created_at DESC') respond_with(@posts) end end @@ -64,7 +64,7 @@ That's a basic overview but there is a lot more to see such as partials, inherit As opposed to standard RABL gem, this gem separate compiling (a.k.a transforming a RABL-rails template into a Ruby hash) and the actual rendering of the object or collection. This allow to only compile the template once and only Ruby hashes. -The fact of compiling the template outside of any rendering context prevent us to use any instances variables (with the exception of node) in the template because they are rendering objects. So instead, you'll have to use symbols of these variables. For example, to render the collection `@posts` inside your `PostController`, you need to use `:@posts` inside of the template. +The fact of compiling the template outside of any rendering context prevent us to use any instances variables (with the exception of node) in the template because they are rendering objects. So instead, you'll have to use symbols of these variables.For example, to render the collection `@posts` inside your `PostController`, you need to use `:@posts` inside of the template. The only places where you can actually used instance variables are into Proc (or lambda) or into custom node (because they are treated as Proc). @@ -81,4 +81,169 @@ The same rule applies for view helpers such as `current_user` After the template is compiled into a hash, Rabl-rails will use a renderer to do the actual output. Actually, only JSON and XML formats are supported. -## Usage \ No newline at end of file +## Usage + +### Data declaration + +To declare data to use in the template, you can use either `object` or `collection` with the symbol name or your data. + +```ruby +# app/views/users/show.json.rabl +object :@user + +# app/views/users/index.json.rabl +collection :@users +``` + +You can specify root label for the collection using hash or `:root` option + +```ruby + collection :@posts, root: :articles + #is equivalent to + collection :@posts => :articles + + # => { "articles" : [{...}, {...}] } +``` + +There are rares cases when the template doesn't map directly to any object. In these cases, you can set data to false or skip data declaration altogether. + +```ruby + object false + node(:some_count) { |_| @user.posts.count } + child(:@user) { attribute :name } +``` + +### Attributes / Methods + +Basic usage is to declared attributes to include in the response. These can be database attributes or any instance method. + +```ruby + attributes :id, :title, :to_s +``` + +You can aliases these attributes in your response + +```ruby + attributes title: :foo, to_s: :bar + # => { "foo" :