rabl 0.5.3 → 0.5.4

data/CHANGELOG.md

@@ -1,6 +1,15 @@
 # CHANGELOG
 
-## 0.5.2 (Unreleased)
+## 0.5.5 (Unreleased)
+
+## 0.5.4
+
+ * Ensure ActionView is defined before registering Rails template handler (thanks cj)
+
+## 0.5.2-0.5.3
+
+ * Add better support for conditionals for child (thanks gregory)
+ * Fix issue introduced with 'node' and properly clear options (thanks joshbuddy)
 
 ## 0.5.1
 

data/README.md

@@ -1,17 +1,19 @@
 # RABL #
 
-RABL (Ruby API Builder Language) is a Rails and [Padrino](http://padrinorb.com) ruby templating system for generating JSON and XML. When using the ActiveRecord 'to_json' method, I tend to quickly find myself wanting a more expressive and powerful system for generating APIs. This is especially frustrating when the json representation is complex or doesn't match the exact schema defined in the database itself.
+RABL (Ruby API Builder Language) is a Rails and [Padrino](http://padrinorb.com) ruby templating system for generating JSON and XML. When using the ActiveRecord 'to_json' method, I tend to quickly find myself wanting a more expressive and powerful solution for generating APIs.
+This is especially frustrating when the JSON representation is complex or doesn't match the exact schema defined in the database.
 
-I wanted a simple, and flexible system for generating APIs. In particular, I wanted to easily:
+I wanted a simple and flexible system for generating my APIs. In particular, I wanted to easily:
 
  * Create arbitrary nodes named based on combining data in an object
  * Pass arguments to methods and store the result as a child node
- * Partial templates and inheritance to reduce code duplication
- * Easily renaming attributes from their name in the model
- * Simple way to append attributes from a child into the parent
- * Include nodes only if a certain condition is met
+ * Render partial templates and inherit to reduce code duplication
+ * Rename or alias attributes to change the name from the model
+ * Append attributes from a child into a parent node
+ * Include nodes only if a certain condition has been met
 
-Anyone who has tried the 'to_json' method used in ActiveRecord for generating a json response has felt the pain of this restrictive approach. RABL is a general templating system created to solve all of those problems.
+Anyone who has tried the 'to_json' method used in ActiveRecord for generating a JSON response has felt the pain of this restrictive approach.
+RABL is a general templating system created to solve these problems in an entirely new way.
 
 ## Installation ##
 
@@ -32,7 +34,7 @@ gem 'yajl-ruby'
 
 and run `bundle install` to install the dependency.
 
-If you are using **Rails 2.X, Rails 3, Rails 3.X or Padrino**, RABL works without configuration.
+If you are using **Rails 2.X, Rails 3 or Padrino**, RABL works without configuration.
 
 With Sinatra, or any other tilt-based framework, simply register:
 
@@ -41,12 +43,19 @@ With Sinatra, or any other tilt-based framework, simply register:
 and RABL will be initialized and ready for use. For usage with Sinatra, check out
 the [Sinatra Usage](https://github.com/nesquena/rabl/wiki/Setup-for-Sinatra) guide.
 
+**Note:** Users have reported a few rendering issues with Rails 3.1 and Rails 3.2.
+The [template handler](https://github.com/nesquena/rabl/blob/master/lib/rabl/template.rb) probably needs
+a patch to properly support Rails 3.2. Hopefully I can get to it soon but patches are welcome.
+
 ## Overview ##
 
-The quick idea here is that you can use RABL to generate JSON and XML API based on any arbitrary data source. With RABL, the data is expected to come
-primarily from a model (ORM-agnostic) and the representation of the API output is described in the view with a simple ruby DSL. This allows you to keep your data separate from the JSON or XML you wish to output.
+You can use RABL to generate JSON and XML based APIs from any ruby object.
+With RABL, the data typically is derived primarily from models (ORM-agnostic) and the representation of the API output is described within
+a view template using a simple ruby DSL. This allows you to keep your data separated from the JSON or XML you wish to output.
 
-Once you have installed RABL (explained above), you can construct a RABL view template and then render the template from your Sinatra, Padrino or Rails applications from the controller (or route) very easily. Using [Padrino](http://padrinorb.com) as an example, assuming you have a `Post` model filled with blog posts, you can render an API representation (both JSON and XML) by creating a route:
+Once you have installed RABL (explained above), you can construct a RABL view template and then render the template
+from your Sinatra, Padrino or Rails applications from the controller (or route) very easily. Using [Padrino](http://padrinorb.com) as an
+example, assuming you have a `Post` model filled with blog posts, you can render an API representation (both JSON and XML) by creating a route:
 
 ```ruby
 # app/app.rb
@@ -79,7 +88,7 @@ Which would output the following JSON or XML when visiting `http://localhost:300
 }]
 ```
 
-That's the basic overview but there is a lot more (partials, inheritance, custom nodes, etc). Read the full details below of RABL below.
+That's a basic overview but there is a lot more to see such as partials, inheritance, custom nodes, etc. Read the full details of RABL below.
 
 ## Configuration ##
 
@@ -174,11 +183,11 @@ There can also be odd cases where the root-level of the response doesn't map dir
 
 ```ruby
 object false
-code(:some_count) { |m| @user.posts.count }
+node(:some_count) { |m| @user.posts.count }
 child(@user) { attribute :name }
 ```
 
-In those cases, object can be assigned to 'false' and child nodes can be constructed independently.
+In those cases, object can be assigned to 'false' and nodes can be constructed free-form.
 
 ### Attributes ###
 
@@ -247,11 +256,11 @@ Use glue to add additional attributes to the parent object.
 
 ### Custom Nodes ###
 
-This will generate a json response based on the result of the code block:
+This will generate a json response based on the result of the `node` block:
 
 ```ruby
 # app/views/users/show.json.rabl
-code :full_name do |u|
+node :full_name do |u|
   u.first_name + " " + u.last_name
 end
 ```
@@ -260,28 +269,28 @@ or a custom node that exists only if a condition is true:
 
 ```ruby
 # m is the object being rendered, also supports :unless
-code(:foo, :if => lambda { |m| m.has_foo? }) do |m|
+node(:foo, :if => lambda { |m| m.has_foo? }) do |m|
   m.foo
 end
 ```
 
-or don't pass a name and have the code block merged into the response:
+or don't pass a name and have the node block merged into the response:
 
 ```ruby
-code do |u|
+node do |u|
   { :full_name => u.first_name + " " + u.last_name }
   # => { full_name : "Bob Johnson" }
 end
 ```
 
-You can use custom "code" nodes to create flexible representations of a value utilizing all the data from the model.
+You can use custom nodes like these to create flexible representations of a value utilizing all the data from the model.
 
 ### Partials ###
 
 Often you need to access other data objects in order to construct custom nodes in more complex associations. You can get access to the rabl representation of another data object by rendering a RABL partial:
 
 ```ruby
-code :location do
+node :location do
   { :city => @city, :address => partial("users/address", :object => @address) }
 end
 ```
@@ -289,7 +298,7 @@ end
 or event access an object associated with the parent model:
 
 ```ruby
-code :location do |m|
+node :location do |m|
   { :city => m.city, :address => partial("users/address", :object => m.address) }
 end
 ```
@@ -307,7 +316,7 @@ RABL has the ability to extend other "base" rabl templates and additional attrib
 # app/views/users/advanced.json.rabl
 extends "users/base" # another RABL template in "app/views/users/base.json.rabl"
 
-code :can_drink do |m|
+node :can_drink do |m|
   m.age > 21
 end
 ```
@@ -334,7 +343,7 @@ object @post
 # Access instance variables
 child(@user => :user) { ... }
 # or Rails helpers
-code(:formatted_body) { |post| simple_format(post.body) }
+node(:formatted_body) { |post| simple_format(post.body) }
 ```
 
 There should be no problem fetching the appropriate data to construct a response.
@@ -362,10 +371,28 @@ Note that RABL can be nested arbitrarily deep within child nodes to allow for th
 
 ### Advanced Usage ###
 
+Links to resources for advanced usage:
+
  * Rendering JSON for a tree structure using RABL: https://github.com/nesquena/rabl/issues/70
  * Layouts (erb, haml and rabl) in RABL: https://github.com/nesquena/rabl/wiki/Using-Layouts
  * Backbone or [Ember.js](http://www.emberjs.com) Integration: https://github.com/nesquena/rabl/wiki/Backbone-Integration
 
+Please add your own usages and let me know so we can add them here!
+
+### Tutorials ###
+
+Tutorials can always be helpful when first getting started:
+
+ * [Railscasts #322](http://railscasts.com/episodes/322-rabl)
+ * http://blog.joshsoftware.com/2011/12/23/designing-rails-api-using-rabl-and-devise/
+ * http://engineering.gomiso.com/2011/06/27/building-a-platform-api-on-rails/
+ * http://blog.lawrencenorton.com/better-json-requests-with-rabl
+ * http://www.rodrigoalvesvieira.com/developing-json-api-rails-rabl/
+ * http://tech.favoritemedium.com/2011/06/using-rabl-in-rails-json-web-api.html
+ * http://seesparkbox.com/foundry/better_rails_apis_with_rabl
+
+Let me know if there's any other useful resources.
+
 ### Troubleshooting ###
 
  * Redundant calls for a collection: https://github.com/nesquena/rabl/issues/142#issuecomment-2969107
@@ -399,6 +426,9 @@ Thanks to [Miso](http://gomiso.com) for allowing me to create this for our appli
 * [Luke van der Hoeven](https://github.com/plukevdh) - Support non-ORM objects in templates
 
 and many more contributors listed in the [CHANGELOG](https://github.com/nesquena/rabl/blob/master/CHANGELOG.md).
+
+Want to contribute support for another format? Check out patch for [msgpack support](https://github.com/nesquena/rabl/pull/69).
+
 Please fork and contribute, any help in making this project better is appreciated!
 
 ## Inspirations ##
@@ -417,4 +447,4 @@ See the [examples](https://github.com/nesquena/rabl/tree/master/examples) direct
 
 ## Copyright
 
-Copyright © 2011 Nathan Esquenazi. See [MIT-LICENSE](https://github.com/nesquena/rabl/blob/master/MIT-LICENSE) for details.
+Copyright © 2011-2012 Nathan Esquenazi. See [MIT-LICENSE](https://github.com/nesquena/rabl/blob/master/MIT-LICENSE) for details.

data/lib/rabl/builder.rb

@@ -4,7 +4,7 @@ module Rabl
 
     # Constructs a new ejs hash based on given object and options
     # options = { :format => "json", :attributes, :root => true,
-    #   :child_root => true, :code, :child, :glue, :extends }
+    #   :child_root => true, :node, :child, :glue, :extends }
     def initialize(data, options={}, &block)
       @options    = options
       @_scope     = options[:scope]
@@ -24,10 +24,10 @@ module Rabl
       @options[:attributes].each_pair do |attribute, name|
         attribute(attribute, :as => name)
       end if @options.has_key?(:attributes)
-      # Code
-      @options[:code].each do |settings|
-        code(settings[:name], settings[:options], &settings[:block])
-      end if @options.has_key?(:code)
+      # Node
+      @options[:node].each do |settings|
+        node(settings[:name], settings[:options], &settings[:block])
+      end if @options.has_key?(:node)
       # Children
       @options[:child].each do |settings|
         child(settings[:data], settings[:options], &settings[:block])
@@ -56,11 +56,11 @@ module Rabl
     end
     alias_method :attributes, :attribute
 
-    # Creates an arbitrary code node that is included in the json output
+    # Creates an arbitrary node that is included in the json output
     # node(:foo) { "bar" }
-    # code(:foo) { "bar" }
-    # code(:foo, :if => lambda { |m| m.foo.present? }) { "bar" }
-    def code(name, options={}, &block)
+    # node(:foo) { "bar" }
+    # node(:foo, :if => lambda { |m| m.foo.present? }) { "bar" }
+    def node(name, options={}, &block)
       return unless resolve_condition(options)
       result = block.call(@_object)
       if name.present?
@@ -69,7 +69,7 @@ module Rabl
         @_result.merge!(result) if result
       end
     end
-    alias_method :node, :code
+    alias_method :code, :node
 
     # Creates a child node that is included in json output
     # child(@user) { attribute :full_name }
@@ -81,7 +81,7 @@ module Rabl
       include_root = is_collection?(object) && @options[:child_root] # child @users
       engine_options = @options.slice(:child_root).merge(:root => include_root)
       object = { object => name } if data.respond_to?(:each_pair) && object # child :users => :people
-      @_result[name] = self.object_to_hash(object, engine_options, &block) 
+      @_result[name] = self.object_to_hash(object, engine_options, &block)
     end
 
     # Glues data from a child node to the json_output

data/lib/rabl/engine.rb

@@ -102,14 +102,14 @@ module Rabl
     end
     alias_method :attributes, :attribute
 
-    # Creates an arbitrary code node that is included in the json output
-    # code(:foo) { "bar" }
-    # code(:foo, :if => lambda { ... }) { "bar" }
-    def code(name = nil, options={}, &block)
-      @_options[:code] ||= []
-      @_options[:code] << { :name => name, :options => options, :block => block }
+    # Creates an arbitrary node that is included in the json output.
+    # node(:foo) { "bar" }
+    # node(:foo, :if => lambda { ... }) { "bar" }
+    def node(name = nil, options={}, &block)
+      @_options[:node] ||= []
+      @_options[:node] << { :name => name, :options => options, :block => block }
     end
-    alias_method :node, :code
+    alias_method :code, :node
 
     # Creates a child node that is included in json output
     # child(@user) { attribute :full_name }
@@ -194,7 +194,7 @@ module Rabl
     def clear_compile_state
       @_options.delete(:extends)
       @_options.delete(:attributes)
-      @_options.delete(:code)
+      @_options.delete(:node)
       @_options.delete(:child)
       @_options.delete(:glue)
     end

data/lib/rabl/template.rb

@@ -20,7 +20,7 @@ if defined?(Tilt)
 end
 
 # Rails 2.X Template
-if defined?(Rails) && Rails.version =~ /^2/
+if defined?(ActionView) && defined?(Rails) && Rails.version =~ /^2/
   require 'action_view/base'
   require 'action_view/template'
 
@@ -41,7 +41,7 @@ if defined?(Rails) && Rails.version =~ /^2/
 end
 
 # Rails 3.X Template
-if defined?(Rails) && Rails.version =~ /^3/
+if defined?(ActionView) && defined?(Rails) && Rails.version =~ /^3/
   module ActionView
     module Template::Handlers
       class Rabl

data/lib/rabl/version.rb

@@ -1,3 +1,3 @@
 module Rabl
-  VERSION = "0.5.3"
+  VERSION = "0.5.4"
 end

metadata

@@ -2,7 +2,7 @@
 name: rabl
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors: 
 - Nathan Esquenazi
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-23 00:00:00 Z
+date: 2012-02-10 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: multi_json