cache_rocket 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 253c1301a5bd797c31657884b822fcc7cd5a49c2
-  data.tar.gz: 58cdcfd0547b68fcb0cb9085438f6ab08b97823e
+  metadata.gz: 378ac5399bdb7f58e8c5b3dfeaea5a76c4369997
+  data.tar.gz: 6d0835c56392e598f0b2fff73c6296bb25efd2be
 SHA512:
-  metadata.gz: 86f7c8e63ca68e93818dc228406e145526784d9b43149714996ad3bb448ada21e3aad6d7c61663e189772f4b429f069da1660e6ad35b01548a4ff97c8bde7f4b
-  data.tar.gz: 10021e25b8d1934d574ed6c3168af71f7a799723647f048f356934905de452f1f26fb31cbeed75850d1464d66f7f650ff0883e7075debd5772c5386c3d13fcc3
+  metadata.gz: 85ff2503338f81cc30a5f9ccb68917e1ff9cd3395294ae7a51503c6f4e46920d25b76d84d5d0ee87277b9a134eb2d603e235cbdcd416f247c454ecb8e01dcdaf
+  data.tar.gz: 47af1c4e271361ae739086a237c574d5bca195eee62ea06557d417db16c2c10a62b405e94b47d7e01c7b7e9bec1d7218dec268a409d5125d90075ab2263cdfd6

data/README.md

@@ -14,7 +14,7 @@ CacheRocket improves server-side fragment caching efficiency in Rails.
 CacheRocket allows caching more generic html fragments and allows the contents of the cached fragments
 to be replaced with dynamic content.
 
-### Install
+## Install
 
 Add the gem to your Gemfile:
 
@@ -29,15 +29,48 @@ Most likely you would put this in your `ApplicationHelper`:
 include CacheRocket
 ```
 
-### Use
+## Use
 
 CacheRocket allows you to cache a fragment of html and replace inner html.
 You inject dynamic content into a static, cached outer partial.
-You cache the donut and replace the donut hole.
 
-Assume you have some html that you would like to cache, but cannot because of some uncacheable code nested in the DOM.
+### `cache_replace`
+
+The simplest usage is inline with the `cache_replace` helper. It works
+like Rails' `cache` method, plus it replaces content that you do not want
+to cache because it is impractical or inefficient.
+
+For example:
+
+#### Before
+
+```haml
+.htmls
+  = Time.now
+```
+
+#### After
+
+```haml
+- cache_replace("the-time", replace: { time: Time.now }) do
+  .htmls
+    = cache_replace_key :time
+```
+
+Now the fragment is cached once with a placeholder, and the time is always replaced when rendered.
+
+Obviously, the above example is contrived and would not result in any
+performance benefit. When the block of html you are rendering is large,
+caching can help.
+
+### `render_cached`
+
+`render_cached` has options to deal with partials and collections.
+Use it as a replacement for Rails' `render`, with `replace` options.
 For example:
 
+#### Before
+
 ##### file.html.haml:
 ```haml
 = render 'outer'
@@ -48,20 +81,17 @@ For example:
 .lots
   .of
     .htmls
-      = render 'inner'
+      = Time.now
 ```
 
-##### _inner.html.haml:
-```haml
-= uncacheable_content
-```
+#### After
 
-In the scenario above, you can't cache anything. With `cache_rocket`, you can. Replace `render`
-with `render_cached` in `file`, specify the partial to replace in `outer`, and cache `outer`:
+ Replace `render`
+with `render_cached` in `file`, specify the content to replace, and cache `outer`:
 
 ##### file.html.haml:
 ```haml
-= render_cached 'outer', replace: 'inner'
+= render_cached 'outer', replace: { inner: Time.now }
 ```
 
 ##### _outer.html.haml:
@@ -70,19 +100,39 @@ with `render_cached` in `file`, specify the partial to replace in `outer`, and c
   .lots
     .of
       .htmls
-        = cache_replace_key 'inner'
+        = cache_replace_key :inner
+```
+
+Here is the same example with an inner partial:
+
+#### Before
+
+##### file.html.haml:
+```haml
+= render 'outer'
+```
+
+##### _outer.html.haml:
+```haml
+.lots
+  .of
+    .htmls
+      = render 'inner'
 ```
 
 ##### _inner.html.haml:
-``` haml
-= uncacheable_content
+```haml
+= Time.now
 ```
 
-With the example above, you could also remove the `_inner.html.haml` file altogether, like so:
+#### After
+
+Replace `render` with `render_cached` in `file`,
+specify the partial to replace in `outer`, and cache `outer`:
 
 ##### file.html.haml:
 ```haml
-= render_cached 'outer', replace: { inner: uncacheable_content }
+= render_cached 'outer', replace: 'inner'
 ```
 
 ##### _outer.html.haml:
@@ -94,6 +144,11 @@ With the example above, you could also remove the `_inner.html.haml` file altoge
         = cache_replace_key :inner
 ```
 
+##### _inner.html.haml:
+``` haml
+= Time.now
+```
+
 ### Options
 
 `render_cached` supports several styles of arguments:
@@ -105,16 +160,19 @@ render_cached 'outer', replace: 'inner'
 ```
 
 #### Array of partials to replace
+
 ```ruby
 render_cached 'outer', replace: ['inner', 'footer']
 ```
 
 #### Hash of keys to replace with values
+
 ```ruby
 render_cached 'outer', replace: { key_name: a_helper_method(object) }
 ```
 
 #### Block containing a hash of keys to replace with values
+
 ```ruby
 render_cached 'outer' do
   { key_name: a_helper_method(object) }
@@ -122,12 +180,14 @@ end
 ```
 
 #### Render a collection with hash of keys, using a lambda for each collection item
+
 ```ruby
 render_cached 'outer', collection: objects,
   replace: { key_name: -> (object) { a_helper_method(object) } }
 ```
 
 #### Render a collection with block syntax
+
 ```ruby
 render_cached 'outer', collection: objects do
   { key_name: -> (object) { a_helper_method(object) } }
@@ -135,6 +195,7 @@ end
 ```
 
 #### Render a collection with block syntax with multiple keys
+
 ```ruby
 render_cached 'outer', collection: objects do
   {
@@ -144,12 +205,12 @@ render_cached 'outer', collection: objects do
 end
 ```
 
-### YMMV
+## YMMV
 
 `cache_rocket` is not magic. It should not be used in all situations.
 Benchmark your page rendering times before and after to see if it helps.
 
-### Benefits
+## Benefits
 
 #### More server-side caching
 
@@ -159,41 +220,35 @@ See the example above.
 
 Typically, one would key the `users/bio` partial on the `user` object like so:
 
-##### users/bio.haml:
+##### users/bio.html.haml:
+
 ```haml
 - cache [user, 'bio'] do
   .lots-of-htmls
     = user.bio
 ```
 
-```haml
-= render 'users/bio'
-```
-
 With 1000 users, there are 1000 cached items. This can use a lot of memory.
 Instead we can cache the `users/bio` partial once and replace the content we need using
 `cache_replace`. With 1000 users, we use 1/1000th the memory.
 
-##### users/bio.haml:
+##### users/bio.html.haml:
 ```haml
-- cache('users/bio') do
+- cache_replace('users/bio', replace: { bio: user.bio }) do
   .lots-of-htmls
     = cache_replace_key :bio
 ```
 
-```haml
-= render_cached 'users/bio', replace: { bio: user.bio }
-```
-
 #### Simpler cache keys
 
 If you have a cache key containing multiple models, it will generally be very inefficient:
+
 ```haml
 - cache(user, other_user) do
   = render 'common_interests'
 ```
 
-If the cached content is rarely retrieved, `cache_replace` can help:
+If the cached content is rarely retrieved, `render_cached` can help:
 
 ```haml
 - cache('common_interests') do

data/lib/cache_rocket/fragment.rb

@@ -1,19 +1,19 @@
+# frozen_string_literal: true
+
 module CacheRocket
   class Fragment
     include Key
 
-    attr_accessor :value
-
     def initialize(value)
-      self.value = value
+      @value = value
     end
 
     def to_s
-      value
+      @value
     end
 
     def gsub!(key, value)
-      self.value.gsub! key, value
+      @value.gsub! key, value
     end
 
     def replace(hash, collection)
@@ -22,6 +22,7 @@ module CacheRocket
       else
         replace_from_hash hash
       end
+      self
     end
 
     private
@@ -36,14 +37,14 @@ module CacheRocket
       html = ""
 
       collection.each do |item|
-        html << replace_item_hash(item, replace_hash)
+        html += replace_item_hash(item, replace_hash)
       end
 
-      self.value = html
+      @value = html
     end
 
     def replace_item_hash(item, hash)
-      item_fragment = value.dup
+      item_fragment = @value.dup
 
       hash.each do |key, proc|
         item_fragment.gsub! cache_replace_key(key), proc.call(item)

data/lib/cache_rocket/key.rb

@@ -1,12 +1,10 @@
 module CacheRocket
   module Key
-    CACHE_REPLACE_KEY_OPEN = "<cr "
-
     # string key containing the partial file name or placeholder key.
     # It is a tag that should never be returned to be rendered by the
-    # client, but if so, it will be hidden since CR is not a valid html tag.
+    # client, but if so, it will be hidden since CRK is not a valid html tag.
     def cache_replace_key(key)
-      "#{CACHE_REPLACE_KEY_OPEN}#{key}>".html_safe
+      "<crk #{key}>".html_safe
     end
   end
 end

data/lib/cache_rocket/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CacheRocket
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/cache_rocket.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "active_support/core_ext/string"
 require "cache_rocket/key"
 require "cache_rocket/fragment"
@@ -7,6 +9,7 @@ module CacheRocket
   include Key
 
   ERROR_MISSING_KEY_OR_BLOCK = "You must either pass a `replace` key or a block to render_cached."
+  ERROR_MISSING_KEY = "You must pass a `replace` key to cache_replace."
 
   # Supports 5 options:
   #
@@ -53,4 +56,26 @@ module CacheRocket
 
     fragment.to_s.html_safe
   end
+
+  # This method works like Rails' CacheHelper#cache,
+  # plus it replaces content in the replace hash.
+  # It must have a `replace` option.
+  #
+  # - cache_replace(["key1", "key2"], replace: { name: "x" }) do
+  #   .htmls
+  #     = cache_replace_key :name
+  #
+  # https://github.com/rails/rails/blob/master/actionview/lib/action_view/helpers/cache_helper.rb
+  def cache_replace(name = {}, options = {}, &block)
+    replace_hash = options.delete(:replace)
+    raise(ArgumentError, ERROR_MISSING_KEY) unless replace_hash
+
+    name_options = options.slice(:skip_digest, :virtual_path)
+    safe_concat \
+      Fragment.new(
+        fragment_for(cache_fragment_name(name, name_options), options, &block)
+      ).replace(replace_hash, nil).to_s.html_safe
+
+    nil
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cache_rocket
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Tee Parham
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-30 00:00:00.000000000 Z
+date: 2017-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -85,8 +85,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: Rails rendering extension for server-side html caching
 test_files: []
+has_rdoc: