If used without nesting, this is a simple wrapper for Rails’ fragment caching. See Caching with Rails for more information on fragment caching.

If used in a nested manner, 2 items are stored in the cache: the fragment, and the list of keys used by the inner caches. This allows the outer cache to generate new fragments if any of the inner elements have changed.


<def tag="card" for="Foo">
  <nested-cache route-on suffix="card" methods="id,updated_at">
    <card without-header>

  <collection: replace>
    <nested-cache suffix="collection" methods="count">
      <collection restore/>

The collection cache will now be regenerated when either the count or the updated_field on any foo changes. This will work even if the collection is a heterogeneous array of foos and bars each with different cache keys.


The context (aka this) for the inner caches must be accessible from the outer cache. In other words, you have to use field= and its abbreviation, the colon form to switch contexts rather than using with=.

Also, all caches must fully enclose or be fully enclosed by any forms.

This is illegal for both reasons:

<nested-cache suffix="outer">
  <form with="&this.comments.new">
    <nested-cache suffix="inner">

replace with:

<nested-cache suffix="outer">
  <do field="comments">
    <nested-cache:new suffix="inner">
      <form ...>


All extra attributes are used as non-hierarchical cache keys, so for inner caches these should either be constants or be manually propagated to the outer caches

methods: A comma separated list of methods or fields that can be called on the context (aka this) to produce cache keys. Example: methods=”id,updated_at”. Inner methods may be accessed by using dots. Example: methods=”comments.first.updated_at”. If the method throws an ArgumentError, it is retried passing in current_user. This allows permission functions to be used: methods=”updatable_by?”.

query-params: A comma separated list of query (or post) parameters that should be cache keys. Example: query-params=”sort,search,page”

route-on: Rails fragment caching uses the the current route to build its cache key. If you are caching an item that will be used in multiple different actions, you can specify route-on to ensure that the different actions can share the cache. You can pass either an object or a path to route-on. If you pass an object, it is converted to a path with url_for. If you specify route-on without a value, this is used. An alternative to using route-on is to specify controller, action and any other required path parameters explicitly. For example route-on=”&posts_path” is identical to controller=”posts” action=”index”. If you do not specify route-on or controller, action, etc., params[:page_path] or the current action is used. route-on is a non-hierarchical key: if any of its parameters are significant (id often is), make sure to add them to the methods attribute.


If you have sweepers, you probably want <swept-cache> instead.

Any Hobo tag that can generate a page refresh, such as filter-menu, table-plus or page-nav stores query parameters such as search, sort & page so that these are not lost when the tag is used to refresh the page. These will need to be added to the query-params for any cache containing such tags.

Show Source

Edit this page