module ActionController::Caching::Fragments - actionpack-4.2.4 Documentation

# module ActionController::Caching::Fragments

Fragment caching is used for caching various blocks within views 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. See ActionView::Helpers::CacheHelper for more information.

While it's strongly recommended that you use key-based cache expiration (see links in CacheHelper for more information), it is also possible to manually expire caches. For example:

    expire_fragment('name_of_cache')

### Public Instance Methods

expire_fragment(key, options = nil) click to toggle source

Removes fragments from the cache.

`key` can take one of three forms:

- String - This would normally take the form of a path, like `pages/45/notes`.

- Hash - Treated as an implicit call to `url_for`, like `{ controller: 'pages', action: 'notes', id: 45}`

- Regexp - Will remove any fragment that matches, so `%r{pages/\d*/notes}` might remove all notes. Make sure you don't use anchors in the regex (`^` or `$`) because the actual filename matched looks like `./cache/filename/path.cache`. 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 `delete` method (or `delete_matched`, for Regexp keys).

    # File lib/action_controller/caching/fragments.rb, line 79
    def expire_fragment(key, options = nil)
      return unless cache_configured?
      key = fragment_cache_key(key) unless key.is_a?(Regexp)

      instrument_fragment_cache :expire_fragment, key do
        if key.is_a?(Regexp)
          cache_store.delete_matched(key, options)
        else
          cache_store.delete(key, options)
        end
      end
    end

fragment_cache_key(key) click to toggle source

Given a key (as described in `expire_fragment`), returns a key suitable for use in reading, writing, or expiring a cached fragment. All keys are prefixed with `views/` and uses ActiveSupport::Cache.expand_cache_key for the expansion.

    # File lib/action_controller/caching/fragments.rb, line 21
    def fragment_cache_key(key)
      ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views)
    end

fragment_exist?(key, options = nil) click to toggle source

Check if a cached fragment from the location signified by `key` exists (see `expire_fragment` for acceptable formats).

    # File lib/action_controller/caching/fragments.rb, line 52
    def fragment_exist?(key, options = nil)
      return unless cache_configured?
      key = fragment_cache_key(key)

      instrument_fragment_cache :exist_fragment?, key do
        cache_store.exist?(key, options)
      end
    end

read_fragment(key, options = nil) click to toggle source

Reads a cached fragment from the location signified by `key` (see `expire_fragment` for acceptable formats).

    # File lib/action_controller/caching/fragments.rb, line 40
    def read_fragment(key, options = nil)
      return unless cache_configured?

      key = fragment_cache_key(key)
      instrument_fragment_cache :read_fragment, key do
        result = cache_store.read(key, options)
        result.respond_to?(:html_safe) ? result.html_safe : result
      end
    end

write_fragment(key, content, options = nil) click to toggle source

Writes `content` to the location signified by `key` (see `expire_fragment` for acceptable formats).

    # File lib/action_controller/caching/fragments.rb, line 27
    def write_fragment(key, content, options = nil)
      return content unless cache_configured?

      key = fragment_cache_key(key)
      instrument_fragment_cache :write_fragment, key do
        content = content.to_str
        cache_store.write(key, content, options)
      end
      content
    end