rabl 0.6.1 → 0.6.2

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 0.6.2
+
+  * Adds template caching support for Rails (Thanks @databyte)
+
 ## 0.6.1
 
   * Upgrade dependency to multi_json 1.1.0 (Thanks @geronimo)

data/README.md

@@ -98,6 +98,7 @@ RABL is intended to require little to no configuration to get working. This is t
 # config/initializers/rabl_init.rb
 Rabl.configure do |config|
   # Commented as these are defaults
+  # config.cache_all_output = false
   # config.cache_sources = false
   # config.json_engine = nil # Any multi\_json engines
   # config.msgpack_engine = nil # Defaults to ::MessagePack
@@ -120,8 +121,12 @@ output if the incoming request has a 'callback' parameter.
 If `cache_sources` is set to `true`, template lookups will be cached for improved performance.
 The cache can be reset manually by running `Rabl.reset_source_cache!` within your application.
 
-Note that the `json_engine` option uses the [multi_json](http://intridea.com/2010/6/14/multi-json-the-swappable-json-handler) intelligent engine
-defaults so in most cases you **don't need to configure this** directly. If you wish to use yajl as
+If `cache_all_output` is set to `true` then every template including each individual template used as part of a collection will be cached separately.
+Additionally, anything within child, glue and partial will also be cached separately.
+To cache just a single template, see the section titled 'Caching' below.
+
+Note that the `json_engine` option uses [multi_json](http://intridea.com/2010/6/14/multi-json-the-swappable-json-handler) engine
+defaults so that in most cases you **don't need to configure this** directly. If you wish to use yajl as
 the primary JSON encoding engine simply add that to your Gemfile:
 
 ```ruby
@@ -455,6 +460,60 @@ end
 This will display the quiz object with nested questions and answers as you would expect with a quiz node, and embedded questions and answers.
 Note that RABL can be nested arbitrarily deep within child nodes to allow for these representations to be defined.
 
+### Caching ###
+
+Caching works by saving the entire template output to the configured cache_store in your application. Note that caching is currently **only available** for
+Rails but support for other frameworks is planned in a future release. 
+
+For Rails, requires `action_controller.perform_caching` to be set to true in your environment, and for `cache` to be set to a key (object that responds to cache_key method, array or string).
+
+```ruby
+# app/views/users/show.json.rabl
+object @quiz
+cache @quiz # key = rabl/quiz/[cache_key]
+attribute :title
+```
+
+The `cache` keyword accepts the same parameters as fragment caching for Rails.
+
+```ruby
+cache @user            # calls @user.cache_key
+cache ['keel', @user]  # calls @user.cache_key and prefixes with kewl/
+cache 'lists'          # explicit key of 'lists'
+cache 'lists', expires_in: 1.hour
+```
+
+The cache keyword is used from within the base template. It will ignore any cache keys specified in an extended template or within partials.
+
+```ruby
+# app/views/users/index.json.rabl
+collection @users
+cache @users  # key = rabl/users/[cache_key]/users/[cache_key]/...
+
+extends "users/show"
+```
+
+and within the inherited template:
+
+```ruby
+# app/views/users/show.json.rabl
+object @user
+cache @user # will be ignored
+
+attributes :name, :email
+```
+Caching can significantly speed up the rendering of RABL templates in production and is strongly recommended when possible.
+
+### Content Type Assignment ###
+
+Currently in RABL, the content-type of your response is not set automatically. This is because RABL is intended
+to work for any Rack-based framework and as agostic to format as possible.
+Check [this issue](https://github.com/nesquena/rabl/issues/185#issuecomment-4501232) for more
+details, and if you have any ideas or patches please let me know.
+
+In the meantime, be sure to set the proper content-types if needed. This is usually pretty simple in both
+Rails and Padrino. I recommend a before_filter on that controller or directly specified in an action.
+
 ## Resources ##
 
 There are many resources available relating to RABL including the [RABL Wiki](https://github.com/nesquena/rabl/wiki),
@@ -535,6 +594,7 @@ 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
 * [Andrey Voronkov](https://github.com/Antiarchitect) - Added BSON format support
 * [Alli Witheford](https://github.com/alzeih) - Added Plist format support
+* [David Sommers](https://github.com/databyte) - Added template caching support for Rails
 
 and many more contributors listed in the [CHANGELOG](https://github.com/nesquena/rabl/blob/master/CHANGELOG.md).
 

data/fixtures/ashared/views/posts/{index.json.rabl → index.rabl}

@@ -1,4 +1,5 @@
 collection @posts => :articles
+cache ['kittens!', @posts]
 
 extends "posts/show"
 

data/fixtures/ashared/views/posts/{show.json.rabl → show.rabl}

@@ -1,4 +1,5 @@
 object @post
+cache @post
 
 attributes :title, :body
 attributes :created_at => :posted_at

data/fixtures/rails2/Gemfile

@@ -1,8 +1,8 @@
 source :gemcutter
 gem "rails", "~> 2.3.14"
-gem "sqlite3-ruby", :require => "sqlite3"
+gem "sqlite3", :require => "sqlite3"
 gem 'json'
 gem 'rabl', :path => File.expand_path(File.dirname(__FILE__) + "/../../")
 
 gem 'riot', :group => "test"
-gem 'rack-test', :require => "rack/test", :group => "test"
+gem 'rack-test', :require => "rack/test", :group => "test"

data/fixtures/rails3/app/controllers/posts_controller.rb

@@ -1,5 +1,5 @@
 class PostsController < ApplicationController
-  respond_to :json
+  respond_to :json, :xml
 
   def index
     @posts = Post.all(:order => "id ASC")

data/fixtures/rails3/test/functional/posts_controller_test.rb

@@ -7,11 +7,14 @@ rescue LoadError # Rails
   require File.expand_path(File.dirname(__FILE__) + '/../test_helper.rb')
 end
 
+require 'rexml/document'
+
 context "PostsController" do
   helper(:json_output) { JSON.parse(last_response.body) }
 
   setup do
     create_users!
+    Rails.cache.clear
     Post.delete_all
     @post1 = Post.create(:title => "Foo", :body => "Bar", :user_id => @user1.id)
     @post2 = Post.create(:title => "Baz", :body => "Bah", :user_id => @user2.id)
@@ -78,7 +81,7 @@ context "PostsController" do
       json_output['post']
     end
 
-     # Attributes (regular)
+    # Attributes (regular)
     asserts("contains post title") { topic['title'] }.equals { @post1.title }
     asserts("contains post body")  { topic['body'] }.equals { @post1.body }
 
@@ -105,4 +108,71 @@ context "PostsController" do
       asserts("contains date partial with full")  { topic['full'] }.equals { @post1.created_at.iso8601 }
     end # date node
   end # show action
+
+  context "for index action with caching in json" do
+    helper(:cache_hit) do |key|
+      Rails.cache.read(ActiveSupport::Cache.expand_cache_key(key, :rabl))
+    end
+
+    setup do
+      mock(ActionController::Base).perform_caching.any_number_of_times { true }
+      get "/posts.json"
+    end
+
+    asserts("contains post titles") do
+      json_output['articles'].map { |o| o['article']['title'] }
+    end.equals { @posts.map(&:title) }
+
+    asserts(:body).equals { cache_hit ['kittens!', @posts, nil, 'json'] }
+  end # index action, caching, json
+
+  context "for index action with caching in xml" do
+    helper(:cache_hit) do |key|
+      Rails.cache.read(ActiveSupport::Cache.expand_cache_key(key, :rabl))
+    end
+
+    setup do
+      mock(ActionController::Base).perform_caching.any_number_of_times { true }
+      get "/posts.xml"
+    end
+
+    asserts("contains post titles") do
+      doc = REXML::Document.new topic.body
+      doc.elements.inject('articles/article/title', []) {|arr, ele| arr << ele.text}
+    end.equals { @posts.map(&:title) }
+
+    asserts(:body).equals { cache_hit ['kittens!', @posts, nil, 'xml'] }
+  end # index action, caching, xml
+
+  context "for show action with caching" do
+    helper(:cache_hit) do |key|
+      Rails.cache.read(ActiveSupport::Cache.expand_cache_key(key, :rabl))
+    end
+
+    setup do
+      mock(ActionController::Base).perform_caching.any_number_of_times { true }
+      get "/posts/#{@post1.id}"
+    end
+
+    asserts("contains post title") { json_output['post']['title'] }.equals { @post1.title }
+
+    asserts(:body).equals { cache_hit [@post1, nil, 'json'] }
+  end # show action, caching, json
+
+  context "cache_all_output" do
+    helper(:cache_hit) do |key|
+      Rails.cache.read(ActiveSupport::Cache.expand_cache_key([key, 'article', 'json'], :rabl))
+    end
+
+    setup do
+      mock(ActionController::Base).perform_caching.any_number_of_times { true }
+      Rabl.configuration.cache_all_output = true
+      get "/posts"
+    end
+
+    asserts("contains cache hits per object (posts by title)") do
+      json_output['articles'].map { |o| o['article']['title'] }
+    end.equals { @posts.map{ |p| cache_hit(p)['article'][:title] } }
+  end  # index action, cache_all_output
+
 end

data/fixtures/sinatra_test/app.rb

@@ -24,21 +24,21 @@ class SinatraTest < Sinatra::Application
 
   get "/posts" do
     @posts = Post.order("id ASC")
-    render :rabl, :"posts/index.json", :format => "json"
+    render :rabl, :"posts/index", :format => "json"
   end
 
   get "/posts/:id" do
     @post = Post.find(params[:id])
-    render :rabl, :"posts/show.json", :format => "json"
+    render :rabl, :"posts/show", :format => "json"
   end
 
   get "/users" do
     @users = User.order("username ASC")
-    render :rabl, :"users/index", :format => "json"
+    render :rabl, :"users/index.json", :format => "json"
   end
 
   get "/users/:id" do
     @user = User.find(params[:id])
-    render :rabl, :"users/show", :format => "json"
+    render :rabl, :"users/show.json", :format => "json"
   end
 end

data/lib/rabl/builder.rb

@@ -15,7 +15,10 @@ module Rabl
     # build(@user, :format => "json", :attributes => { ... }, :root_name => "user")
     def build(object, options={})
       @_object = object
-      compile_hash(options)
+
+      cache_results do
+        compile_hash(options)
+      end
     end
 
     protected
@@ -109,8 +112,6 @@ module Rabl
       @_result.merge!(result) if result
     end
 
-    protected
-
     # resolve_condition(:if => true) => true
     # resolve_condition(:if => lambda { |m| false }) => false
     # resolve_condition(:unless => lambda { |m| true }) => true
@@ -120,5 +121,19 @@ module Rabl
       result = options[:unless] == false || (options[:unless].respond_to?(:call) && !options[:unless].call(@_object)) if options.has_key?(:unless)
       result
     end
+
+    private
+
+    # Caches the results of the block based on object cache_key
+    # cache_results { compile_hash(options) }
+    def cache_results(&block)
+      if template_cache_configured? && Rabl.configuration.cache_all_output && @_object.respond_to?(:cache_key)
+        result_cache_key = [@_object, @options[:root_name], @options[:format]]
+        fetch_result_from_cache(result_cache_key, &block)
+      else # skip cache
+        yield
+      end
+    end
+
   end
 end

data/lib/rabl/configuration.rb

@@ -35,6 +35,7 @@ module Rabl
     attr_writer   :plist_engine
     attr_writer   :xml_options
     attr_accessor :cache_sources
+    attr_accessor :cache_all_output
 
     DEFAULT_XML_OPTIONS = { :dasherize  => true, :skip_types => false }
 
@@ -53,6 +54,7 @@ module Rabl
       @plist_engine          = nil
       @xml_options           = {}
       @cache_sources         = false
+      @cache_all_output      = false
     end
 
     # @param [Symbol, String, #encode] engine_name The name of a JSON engine,

data/lib/rabl/engine.rb

@@ -24,7 +24,7 @@ module Rabl
         instance_eval(@_source) if @_source.present?
       end
       instance_eval(&block) if block_given?
-      self.send("to_" + @_options[:format].to_s)
+      cache_results { self.send("to_" + @_options[:format].to_s) }
     end
 
     # Returns a hash representation of the data object
@@ -34,6 +34,7 @@ module Rabl
       data = data_object(@_data)
       builder = Rabl::Builder.new(options)
       options[:root_name] = determine_object_root(@_data, options[:root])
+
       if is_object?(data) || !data # object @user
         builder.build(data, options)
       elsif is_collection?(data) # collection @users
@@ -113,6 +114,16 @@ module Rabl
       self.object(data_object(data).to_a) if data
     end
 
+    # Sets the cache key to be used by ActiveSupport::Cache.expand_cache_key
+    # cache @user            # calls @user.cache_key
+    # cache ['rabl', @user]  # calls @user.cache_key and prefixes with rabl/
+    # cache 'user'           # explicit key of 'user'
+    # cache 'user', expires_in: 1.hour
+    # options is passed through to the cache store
+    def cache(key, options = nil)
+      @_cache = [key, options]
+    end
+
     # Indicates an attribute or method should be included in the json output
     # attribute :foo, :as => "bar"
     # attribute :foo => :bar
@@ -221,5 +232,19 @@ module Rabl
       @_options[:extends] = []
       @_options[:root_name]  = nil
     end
+
+    # Caches the results of the block based on object cache_key
+    # cache_results { compile_hash(options) }
+    def cache_results(&block)
+      _cache = @_cache if defined?(@_cache)
+      cache_key, cache_options = *_cache || nil
+      if template_cache_configured? && cache_key
+        result_cache_key = Array(cache_key) + [@_options[:root_name], @_options[:format]]
+        fetch_result_from_cache(result_cache_key, cache_options, &block)
+      else # skip caching
+        yield
+      end
+    end
+
   end
 end

data/lib/rabl/helpers.rb

@@ -78,5 +78,17 @@ module Rabl
       defined?(@_collection_name) ? @_collection_name : nil
     end
 
+    # Fetches a key from the cache and stores rabl template result otherwise
+    # fetch_from_cache('some_key') { ...rabl template result... }
+    def fetch_result_from_cache(cache_key, cache_options=nil, &block)
+      expanded_cache_key = ActiveSupport::Cache.expand_cache_key(cache_key, :rabl)
+      Rails.cache.fetch(expanded_cache_key, cache_options, &block) if defined?(Rails)
+    end
+
+    # Returns true if the cache has been enabled for the application
+    def template_cache_configured?
+      defined?(Rails) && defined?(ActionController) && ActionController::Base.perform_caching
+    end
+
   end
 end

data/lib/rabl/version.rb

@@ -1,3 +1,3 @@
 module Rabl
-  VERSION = "0.6.1"
+  VERSION = "0.6.2"
 end

data/test/builder_test.rb

@@ -23,34 +23,26 @@ context "Rabl::Builder" do
   end
 
   context "#to_hash" do
-
     context "when given a simple object" do
-
       setup { builder({ :attributes => { :name => :name } }) }
       asserts "that the object is set properly" do
         topic.build(User.new, :root_name => "user")
       end.equivalent_to({ "user" => { :name => "rabl" } })
-
     end
 
     context "when given an object alias" do
-
      setup { builder({ :attributes => { :name => :name } }) }
       asserts "that the object is set properly" do
         topic.build(User.new, :root_name => "person")
       end.equivalent_to({ "person" => { :name => "rabl" } })
-
     end
 
     context "when specified with no root" do
-
       setup { builder({ :attributes => { :name => :name } }) }
       asserts "that the object is set properly" do
         topic.build(User.new, :root => false)
       end.equivalent_to({ :name => "rabl" })
-
     end
-
   end
 
   context "#attribute" do
@@ -63,7 +55,6 @@ context "Rabl::Builder" do
     end.equals({})
   end
 
-
   context "#node" do
     asserts "that it has node :foo" do
       build_hash @user, :node => [{ :name => :foo, :options => {}, :block => lambda { |u| "bar" } }]
@@ -78,7 +69,6 @@ context "Rabl::Builder" do
   end
 
   context "#child" do
-
     asserts "that it generates if no data present" do
       builder(:child => []).build(@user)
     end.equals({})
@@ -115,9 +105,7 @@ context "Rabl::Builder" do
     end.equivalent_to({ :users => 'xyz'})
   end
 
-
   context "#glue" do
-
     asserts "that it generates if no data present" do
       builder(:glue => []).build(@user)
     end.equals({})
@@ -141,7 +129,6 @@ context "Rabl::Builder" do
   end
 
   context "#extend" do
-
     asserts "that it does not genereate if no data is present" do
       b = builder :extends => [{ :file => 'users/show', :options => {}, :block => lambda { |u| attribute :name  }}]
       mock(b).partial('users/show',{ :object => @user}).returns({}).subject

data/test/engine_test.rb

@@ -17,6 +17,41 @@ context "Rabl::Engine" do
     asserts_topic.assigns :_options
   end
 
+  context "#cache" do
+    context "with cache" do
+      setup do
+        template = rabl %q{
+          cache 'foo'
+        }
+        template.render(Object.new)
+        template.instance_eval('@engine')
+      end
+
+      asserts_topic.assigns(:_cache) { ['foo', nil] }
+    end
+
+    context "with cache and options" do
+      setup do
+        template = rabl %q{
+          cache 'foo', expires_in: 'bar'
+        }
+        template.render(Object.new)
+        template.instance_eval('@engine')
+      end
+
+      asserts_topic.assigns(:_cache) { ['foo', { expires_in: 'bar' }] }
+    end
+
+    context "without cache" do
+      setup do
+        template = RablTemplate.new {}
+        template.render(Object.new)
+        template.instance_eval('@engine')
+      end
+
+      denies(:instance_variable_defined?, :@_cache)
+    end
+  end
 
   context "with defaults" do
     setup do
@@ -27,8 +62,19 @@ context "Rabl::Engine" do
       end
     end
 
-    context "#object" do
+    context "#cache" do
+      asserts "does not modify output" do
+        template = rabl %q{
+          object @user
+          cache @user
+        }
+        scope = Object.new
+        scope.instance_variable_set :@user, User.new
+        template.render(scope)
+      end.matches "{\"user\":{}}"
+    end
 
+    context "#object" do
       asserts "that it sets data source" do
         template = rabl %q{
           object @user
@@ -47,7 +93,6 @@ context "Rabl::Engine" do
         template.render(scope)
       end.equals "{\"person\":{}}"
 
-
       asserts "that it can use non-ORM objects" do
         template = rabl %q{
           object @other
@@ -63,11 +108,9 @@ context "Rabl::Engine" do
         scope.instance_variable_set :@user, User.new
         template.render(scope)
       end.matches "{}"
-
     end
 
     context "#collection" do
-
       asserts "that it sets object to be casted as a simple array" do
         template = rabl %{
           collection @users
@@ -115,7 +158,6 @@ context "Rabl::Engine" do
     end
 
     context "#attribute" do
-
       asserts "that it adds an attribute or method to be included in output" do
         template = rabl %{
           object @user
@@ -145,11 +187,9 @@ context "Rabl::Engine" do
         scope.instance_variable_set :@user, User.new(:name => 'irvine')
         template.render(scope).split('').sort
       end.equals "{\"user\":{\"city\":\"irvine\"}}".split('').sort
-
     end
 
     context "#code" do
-
       asserts "that it can create an arbitraty code node" do
         template = rabl %{
           code(:foo) { 'bar' }
@@ -190,11 +230,9 @@ context "Rabl::Engine" do
         scope.instance_variable_set :@user, User.new(:name => 'leo', :city => 'LA')
         template.render(scope).split('').sort
       end.equals "{\"user\":{\"name\":\"leo\",\"user\":{\"city\":\"LA\"}}}".split('').sort
-
     end
 
     context "#child" do
-
       asserts "that it can create a child node" do
         template = rabl %{
           object @user
@@ -220,7 +258,6 @@ context "Rabl::Engine" do
     end
 
     context "#glue" do
-
       asserts "that it glues data from a child node" do
         template = rabl %{
           object @user
@@ -249,7 +286,6 @@ context "Rabl::Engine" do
     end
 
     context "#object" do
-
       asserts "that it sets data source" do
         template = rabl %q{
           object @user
@@ -270,7 +306,6 @@ context "Rabl::Engine" do
     end
 
     context "#collection" do
-
       asserts "that it sets object to be casted as a simple array" do
         template = rabl %{
           collection @users
@@ -289,7 +324,7 @@ context "Rabl::Engine" do
         template.render(scope)
       end.equals "{\"people\":[{},{}]}"
 
-    asserts "that it sets root node for objects using root option" do
+      asserts "that it sets root node for objects using root option" do
         template = rabl %{
           collection @users, :root => :people
         }
@@ -309,7 +344,6 @@ context "Rabl::Engine" do
     end
 
     context "#attribute" do
-
       asserts "that it adds an attribute or method to be included in output" do
         template = rabl %{
           object @user
@@ -339,11 +373,9 @@ context "Rabl::Engine" do
         scope.instance_variable_set :@user, User.new(:name => 'irvine')
         template.render(scope)
       end.equals "{\"city\":\"irvine\"}"
-
     end
 
     context "#code" do
-
       asserts "that it can create an arbitraty code node" do
         template = rabl %{
           code(:foo) { 'bar' }
@@ -357,11 +389,9 @@ context "Rabl::Engine" do
         }
         template.render(Object.new)
       end.equals "{}"
-
     end
 
     context "#child" do
-
       asserts "that it can create a child node" do
         template = rabl %{
           object @user
@@ -385,7 +415,6 @@ context "Rabl::Engine" do
 
       end.equals "{\"name\":\"leo\",\"person\":{\"city\":\"LA\"}}".split('').sort
 
-
       asserts "that it can be passed conditionals" do
         template = rabl %{
           object @user
@@ -397,11 +426,9 @@ context "Rabl::Engine" do
         template.render(scope).split('').sort
 
       end.equals "{\"name\":\"leo\"}".split('').sort
-
     end
 
     context "#glue" do
-
       asserts "that it glues data from a child node" do
         template = rabl %{
           object @user

data/test/integration/test_init.rb

@@ -1,5 +1,6 @@
 require 'rack/test'
 require 'riot'
+require 'riot/rr'
 
 Riot.pretty_dots
 

metadata

@@ -2,7 +2,7 @@
 name: rabl
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors: 
 - Nathan Esquenazi
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-03-09 00:00:00 Z
+date: 2012-03-21 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: multi_json
@@ -152,12 +152,12 @@ files:
 - fixtures/ashared/models/post.rb
 - fixtures/ashared/models/user.rb
 - fixtures/ashared/views/layouts/application.html.erb
-- fixtures/ashared/views/posts/date.json.rabl
-- fixtures/ashared/views/posts/index.json.rabl
-- fixtures/ashared/views/posts/show.json.rabl
-- fixtures/ashared/views/users/index.rabl
-- fixtures/ashared/views/users/phone_number.rabl
-- fixtures/ashared/views/users/show.rabl
+- fixtures/ashared/views/posts/date.rabl
+- fixtures/ashared/views/posts/index.rabl
+- fixtures/ashared/views/posts/show.rabl
+- fixtures/ashared/views/users/index.json.rabl
+- fixtures/ashared/views/users/phone_number.json.rabl
+- fixtures/ashared/views/users/show.json.rabl
 - fixtures/padrino_test/.components
 - fixtures/padrino_test/.gitignore
 - fixtures/padrino_test/Gemfile
@@ -312,7 +312,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: rabl
-rubygems_version: 1.8.15
+rubygems_version: 1.8.19
 signing_key: 
 specification_version: 3
 summary: General ruby templating with json, bson, xml and msgpack support