rabl 0.1.6 → 0.2.0

data/README.md

@@ -34,6 +34,60 @@ With Sinatra, or any other tilt-based framework, simply register:
 
 and RABL will be initialized and ready for use.
 
+## 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.
+
+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
+get "/posts", :provides => [:json, :xml] do
+  @user = current_user
+  @posts = Post.order("id DESC")
+  render "posts/index"
+end
+```
+
+Then we can create the following RABL template to express the API output of `@posts`:
+
+```ruby
+# app/views/posts/index.rabl
+collection @posts
+attributes :id, :title, :subject
+child(:user) { attributes :full_name }
+node(:read) { |post| post.read_by?(@user) }
+```
+
+Which would output the following JSON or XML when visiting `http://localhost:3000/posts.json`
+
+```json
+[{  post :
+  {
+    id : 5, title: "...", subject: "...",
+    user : { full_name : "..." },
+    read : true
+  }
+}]
+```
+
+That's the basic overview but there is a lot more (partials, inheritance, custom nodes, etc). Read the full details below of RABL below.
+
+## Configuration ##
+
+RABL is intended to require little to no configuration to get working. This is the case in most scenarios, but depending on your needs you may want to set the following global configurations in your application (this block is completely optional):
+
+    # config/initializers/rabl_init.rb
+    Rabl.configure do |config|
+      # Commented as these are the defaults
+      # config.include_json_root = true
+      # config.include_xml_root  = false
+      # config.enable_json_callbacks = false
+    end
+
+Each option specifies behavior related to RABL's output. If `include_json_root` is disabled that removes the root node for each child in the output, and `enable_json_callbacks` enables support for 'jsonp' style callback output if the incoming request has a 'callback' parameter.
+
 ## Usage ##
 
 ### Object Assignment ###
@@ -198,7 +252,6 @@ Note that RABL can be nested arbitrarily deep within child nodes to allow for th
 
 Check out the [Issues](https://github.com/nesquena/rabl/issues) tab for a full list:
 
- * No configuration options yet for how to create the json (root nodes) :(
  * Better Tilt template support (precompiling templates)
  * Benchmarks and performance optimizations
 

data/lib/rabl.rb

@@ -2,11 +2,29 @@ require 'rabl/version'
 require 'rabl/helpers'
 require 'rabl/engine'
 require 'rabl/builder'
+require 'rabl/configuration'
 
 # Rabl.register!
 module Rabl
-  def self.register!
-    require 'rabl/template'
+  class << self
+    def register!
+      require 'rabl/template'
+    end
+
+    # Yields a RABL configuration block
+    # Rabl.configure do |config|
+    #  config.include_json_root     = false
+    #  config.enable_json_callbacks = true
+    # end
+    def configure(&block)
+      yield(self.configuration)
+    end
+
+    # Returns the configuration options set for RABL
+    # Rabl.configuration.include_json_root => false
+    def configuration
+      @_configuration ||= Configuration.new
+    end
   end
 end
 

data/lib/rabl/configuration.rb

@@ -0,0 +1,21 @@
+module Rabl
+  # Rabl.host
+  class Configuration
+    attr_accessor :include_json_root
+    attr_accessor :include_xml_root
+    attr_accessor :enable_json_callbacks
+
+    def initialize
+      @include_json_root     = true
+      @include_xml_root      = false
+      @enable_json_callbacks = false
+    end
+
+    # Allows config options to be read like a hash
+    #
+    # @param [Symbol] option Key for a given attribute
+    def [](option)
+      send(option)
+    end
+  end
+end

data/lib/rabl/engine.rb

@@ -38,15 +38,17 @@ module Rabl
     # Returns a json representation of the data object
     # to_json(:root => true)
     def to_json(options={})
-      options = options.reverse_merge(:root => true, :child_root => true)
+      include_root = Rabl.configuration.include_json_root
+      options = options.reverse_merge(:root => include_root, :child_root => include_root)
       result = @_collection_name ? { @_collection_name => to_hash(options) } : to_hash(options)
-      result.to_json
+      format_json(result.to_json)
     end
 
     # Returns an xml representation of the data object
     # to_xml(:root => true)
     def to_xml(options={})
-      options = options.reverse_merge(:root => false, :child_root => false)
+      include_root = Rabl.configuration.include_xml_root
+      options = options.reverse_merge(:root => include_root, :child_root => include_root)
       to_hash(options).to_xml(:root => data_name(@_data))
     end
 
@@ -130,10 +132,21 @@ module Rabl
     # Returns a guess at the format in this scope
     # default_format => "xml"
     def default_format
-      format = @_scope.respond_to?(:params) && @_scope.params.has_key?(:format) ?
-        @_scope.params[:format] :
-        nil
+      format = self.request_params.has_key?(:format) ? @_scope.params[:format] : nil
       format || "json"
     end
+
+    # Returns the request parameters if available in the scope
+    # request_params => { :foo => "bar" }
+    def request_params
+      @_scope.respond_to?(:params) ? @_scope.params : {}
+    end
+
+    # Returns json embraced with callback if appropriate or plain if not
+    # detect_jsonp({ foo : "bar" }) => "test({ foo : 'bar' })"
+    def format_json(json_output)
+      use_callback = Rabl.configuration.enable_json_callbacks && request_params[:callback].present?
+      use_callback ? "#{request_params[:callback]}(#{json_output})" : json_output
+    end
   end
 end

data/lib/rabl/version.rb

@@ -1,3 +1,3 @@
 module Rabl
-  VERSION = "0.1.6"
+  VERSION = "0.2.0"
 end

metadata

@@ -2,7 +2,7 @@
 name: rabl
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors: 
 - Nathan Esquenazi
@@ -10,8 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-04 00:00:00 -07:00
-default_executable: 
+date: 2011-05-12 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: riot
@@ -78,6 +77,7 @@ files:
 - examples/inherited.json.rabl
 - lib/rabl.rb
 - lib/rabl/builder.rb
+- lib/rabl/configuration.rb
 - lib/rabl/engine.rb
 - lib/rabl/helpers.rb
 - lib/rabl/template.rb
@@ -89,7 +89,6 @@ files:
 - test/models/user.rb
 - test/template_test.rb
 - test/teststrap.rb
-has_rdoc: true
 homepage: https://github.com/nesquena/rabl
 licenses: []
 
@@ -113,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: rabl
-rubygems_version: 1.6.2
+rubygems_version: 1.7.2
 signing_key: 
 specification_version: 3
 summary: General ruby templating for json or xml