rabl 0.0.3 → 0.0.4

data/README.md

@@ -14,23 +14,53 @@ This general templating system solves all of those problems.
 
 ## Installation ##
 
+Install as a gem:
+
     gem install rabl
 
+or add to your Gemfile:
+
+    # Gemfile
+    gem 'rabl'
+
+and run `bundle install` to install the dependency.
+
 ## Usage ##
 
+### Object Assignment ###
+
+To declare the data object to use in the template:
+
+     # app/views/users/show.json.rabl
+     object @user
+
+or a collection works:
+
+     object @users
+
+and this will be used as the default data object for the rendering.
+
+### Attributes ###
+
 Basic usage of the templater:
 
     # app/views/users/show.json.rabl
     attributes :id, :foo, :bar
 
-This will generate a json response with the attributes specified. You can also include arbitrary code:
+or with aliased attributes:
 
-    # app/views/users/show.json.rabl
-    code :full_name do |u|
-      u.first_name + " " + u.last_name
-    end
+    # Take the value of model attribute `foo` and name the node `bar`
+    # { bar : 5 }
+    attribute :foo => :bar
+
+or multiple aliased attributes:
+
+    # { baz : <bar value>, animal : <dog value> }
+    attributes :bar => :baz, :dog => :animal
 
-You can also add children nodes:
+### Child Nodes ###
+
+You can also add children nodes from an arbitrary object:
 
     child @posts => :foobar do
       attributes :id, :title
@@ -42,34 +72,65 @@ or use existing model associations:
       attributes :id, :title
     end
 
-You can also extend other rabl templates to reduce duplication:
+### Glued Attributes ###
+
+You can also append attributes to the root node:
+
+    glue @post do
+      attributes :id => :post_id, :name => :post_name
+    end
+
+Use glue to add additional attributes to the parent object.
+
+### Custom Nodes ###
+
+This will generate a json response with the attributes specified. You can also include arbitrary code:
 
     # app/views/users/show.json.rabl
-    child @address do
-      extends "address/item"
+    code :full_name do |u|
+      u.first_name + " " + u.last_name
     end
 
-or get access to the hash representation of another object:
+You can use custom "code" nodes to create flexible representations of a value utilizing data from the model.
+
+### Partials ###
+
+Often you need to access sub-objects in order to construct your own custom nodes for more complex associations. You can get access to the hash representation of another object:
 
     code :location do
-      { :place => partial("web/users/address", :object => @address) }
+      { :city => @city, :address => partial("web/users/address", :object => @address) }
     end
 
-You can also append attributes to the root node:
+or an object associated to the parent model:
 
-    glue @post do
-      attribute :id => :post_id
+    code :location do |m|
+      { :city => m.city, :address => partial("web/users/address", :object => m.address) }
     end
 
-There is also the ability to extend other rabl templates with additional attributes:
+You can use these to construct arbitrarily complex nodes for APIs.
+
+### Inheritance ###
+
+Another common limitation of many json builders is code redundancy. Typically every representation of an object across endpoints share common attributes or nodes. The nodes for a 'post' object are probably the same or similar in most references throughout the various endpoints.
 
-    extends "base"
+RABL has the ability to extend other "base" rabl templates and additional attributes:
 
-    code :release_year do |m|
-      date = m.release_date || m.series_start
-      date.try(:year)
+    # app/views/users/advanced.json.rabl
+    extends "users/base" # another RABL template in "app/views/users/base.json.rabl"
+
+    code :can_drink do |m|
+      m.age > 21
     end
 
+You can also extend other rabl templates in constructing nodes to reduce duplication:
+
+    # app/views/users/show.json.rabl
+    child @address do
+      extends "address/item"
+    end
+
+Using partials and inheritance can significantly reduce code duplication in your templates.
+
 ## Issues ##
 
  * I am sloppy and once again failed to unit test this. Don't use it in production until I do obviously.

data/lib/rabl/engine.rb

@@ -6,7 +6,8 @@ module Rabl
       @_handler = handler
       @_options = { :handler => @_handler, :vars => @_vars, :engine => self }
       self.copy_instance_variables_from(@_handler, [:@assigns, :@helpers]);
-      @_object = vars[:object] || instance_variable_get("@#{@_handler.controller.controller_name}")
+      @_object = vars[:object] || self.default_object
+      # raise @user.inspect + " - " + @_handler.instance_variable_get(:@options).inspect + " - " + @_handler.inspect
       instance_eval(source_string) if source_string.present?
       instance_eval(&block) if block_given?
     end
@@ -89,5 +90,14 @@ module Rabl
       return object unless object.is_a?(ActiveRecord::Base) || object.first.is_a?(ActiveRecord::Base)
       self.class.new(@_vars.merge(:object => object), @_handler, source, &block).to_hash(:root => false)
     end
+
+    protected
+
+    # Returns a guess at the default object for this template
+    def default_object
+      @_handler.respond_to?(:controller) ?
+        instance_variable_get("@#{@_handler.controller.controller_name}") :
+        nil
+    end
   end
 end

data/lib/rabl/version.rb

@@ -1,3 +1,3 @@
 module Rabl
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rabl
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: 
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Nathan Esquenazi