aboutsummaryrefslogtreecommitdiffstats
path: root/actionpack/lib/action_controller/caching/fragments.rb
blob: 59e24619e3e836a14464b450ca3c5b626fd932e1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
module ActionController #:nodoc:
  module Caching
    # Fragment caching is used for caching various blocks within templates without caching the entire action as a whole. This is useful when
    # certain elements of an action change frequently or depend on complicated state while other parts rarely change or can be shared amongst multiple
    # parties. The caching is done using the cache helper available in the Action View. A template with caching might look something like:
    #
    #   <b>Hello <%= @name %></b>
    #   <% cache do %>
    #     All the topics in the system:
    #     <%= render :partial => "topic", :collection => Topic.find(:all) %>
    #   <% end %>
    #
    # This cache will bind to the name of the action that called it, so if this code was part of the view for the topics/list action, you would
    # be able to invalidate it using <tt>expire_fragment(:controller => "topics", :action => "list")</tt>.
    #
    # This default behavior is of limited use if you need to cache multiple fragments per action or if the action itself is cached using
    # <tt>caches_action</tt>, so we also have the option to qualify the name of the cached fragment with something like:
    #
    #   <% cache(:action => "list", :action_suffix => "all_topics") do %>
    #
    # That would result in a name such as "/topics/list/all_topics", avoiding conflicts with the action cache and with any fragments that use a
    # different suffix. Note that the URL doesn't have to really exist or be callable - the url_for system is just used to generate unique
    # cache names that we can refer to when we need to expire the cache.
    #
    # The expiration call for this example is:
    #
    #   expire_fragment(:controller => "topics", :action => "list", :action_suffix => "all_topics")
    module Fragments
      # Given a key (as described in <tt>expire_fragment</tt>), returns a key suitable for use in reading,
      # writing, or expiring a cached fragment. If the key is a hash, the generated key is the return
      # value of url_for on that hash (without the protocol). All keys are prefixed with "views/" and uses
      # ActiveSupport::Cache.expand_cache_key for the expansion.
      def fragment_cache_key(key)
        ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views)
      end

      def fragment_for(buffer, name = {}, options = nil, &block) #:nodoc:
        if perform_caching
          if fragment_exist?(name,options)
            buffer.concat(read_fragment(name, options))
          else
            pos = buffer.length
            block.call
            write_fragment(name, buffer[pos..-1], options)
          end
        else
          block.call
        end
      end

      # Writes <tt>content</tt> to the location signified by <tt>key</tt> (see <tt>expire_fragment</tt> for acceptable formats)
      def write_fragment(key, content, options = nil)
        return content unless cache_configured?

        key = fragment_cache_key(key)
        event = ActiveSupport::Orchestra.instrument(:write_fragment, :key => key) do
          cache_store.write(key, content, options)
        end

        self.class.log_with_time("Cached fragment miss: #{key}", event.duration)
        content
      end

      # Reads a cached fragment from the location signified by <tt>key</tt> (see <tt>expire_fragment</tt> for acceptable formats)
      def read_fragment(key, options = nil)
        return unless cache_configured?

        key = fragment_cache_key(key)
        event = ActiveSupport::Orchestra.instrument(:read_fragment, :key => key) do
          cache_store.read(key, options)
        end

        self.class.log_with_time("Cached fragment hit: #{key}", event.duration)
        event.result
      end

      # Check if a cached fragment from the location signified by <tt>key</tt> exists (see <tt>expire_fragment</tt> for acceptable formats)
      def fragment_exist?(key, options = nil)
        return unless cache_configured?

        key = fragment_cache_key(key)
        event = ActiveSupport::Orchestra.instrument(:fragment_exist?, :key => key) do
          cache_store.exist?(key, options)
        end

        self.class.log_with_time("Cached fragment exists?: #{key}", event.duration)
        event.result
      end

      # Removes fragments from the cache.
      #
      # +key+ can take one of three forms:
      # * String - This would normally take the form of a path, like
      #   <tt>"pages/45/notes"</tt>.
      # * Hash - Treated as an implicit call to +url_for+, like
      #   <tt>{:controller => "pages", :action => "notes", :id => 45}</tt>
      # * Regexp - Will remove any fragment that matches, so
      #   <tt>%r{pages/\d*/notes}</tt> might remove all notes. Make sure you
      #   don't use anchors in the regex (<tt>^</tt> or <tt>$</tt>) because
      #   the actual filename matched looks like
      #   <tt>./cache/filename/path.cache</tt>. Note: Regexp expiration is
      #   only supported on caches that can iterate over all keys (unlike
      #   memcached).
      #
      # +options+ is passed through to the cache store's <tt>delete</tt>
      # method (or <tt>delete_matched</tt>, for Regexp keys.)
      def expire_fragment(key, options = nil)
        return unless cache_configured?

        key = fragment_cache_key(key) unless key.is_a?(Regexp)
        message = nil

        event = ActiveSupport::Orchestra.instrument(:expire_fragment, :key => key) do
          if key.is_a?(Regexp)
            message = "Expired fragments matching: #{key.source}"
            cache_store.delete_matched(key, options)
          else
            message = "Expired fragment: #{key}"
            cache_store.delete(key, options)
          end
        end

        self.class.log_with_time(message, event.duration)
        event.result
      end
    end
  end
end