Support explicit defintion of resouce name for collection caching.

If a template includes `# Template Collection: ...` anywhere in its
source, that name will be used as the cache name for the partial that is
rendered for the collection.

This allows users to enable collection caching even if the template
doesn't start with `<% cache ... do %>`.

Moreover, the `# Template Collection: ...` notation is recognized in all
template types (and template types other than ERB can define a
resource_cache_call_pattern method to allow the `cache ... do` pattern
to be recognized too).

1 files changed, 15 insertions, 0 deletions

diff --git a/actionview/lib/action_view/helpers/cache_helper.rb b/actionview/lib/action_view/helpers/cache_helper.rb
index 8945575860..797d029317 100644
--- a/actionview/lib/action_view/helpers/cache_helper.rb
+++ b/actionview/lib/action_view/helpers/cache_helper.rb
@@ -137,6 +137,21 @@ module ActionView
       # The automatic cache multi read can be turned off like so:
       #
       #   <%= render @notifications, cache: false %>
+      #
+      # === Explicit Collection Caching
+      #
+      # If the partial template doesn't start with a clean cache call as
+      # mentioned above, you can still benefit from collection caching by
+      # adding a special comment format anywhere in the template, like:
+      #
+      #   <%# Template Collection: notification %>
+      #   <% my_helper_that_calls_cache(some_arg, notification) do %>
+      #     <%= notification.name %>
+      #   <% end %>
+      #
+      # The pattern used to match these is <tt>/# Template Collection: (\S+)/</tt>,
+      # so it's important that you type it out just so.
+      # You can only declare one collection in a partial template file.
       def cache(name = {}, options = {}, &block)
         if controller.respond_to?(:perform_caching) && controller.perform_caching
           safe_concat(fragment_for(cache_fragment_name(name, options), options, &block))