<cache></cache>

Provided by module: Tags: RXML tags

This tag caches the evaluated result of its contents. When the tag is encountered again in a later request, it can thus look up and return that result without evaluating the content again.

Nested <cache> tags are normally cached separately, and they are also recognized so that the enclosing <cache> tags don't cache their contents too. It's thus possible to change the cache parameters or completely disable caching of a certain part of the content inside a <cache> tag.

Note!

This implies that many RXML tags that enclose the inner <cache> tag(s) won't be cached. The reason is that those enclosing tags use the result of the inner <cache> tag(s), which can only be established when the actual context in each request is compared to the cache parameters. See the section below about cache static tags, though.

Besides the value produced by the content, all assignments to RXML variables in any scope are cached. I.e. an RXML code block which produces a value in a variable may be cached, and the same value will be assigned again to that variable when the cached entry is used.

When the content is evaluated, the produced result is associated with a key that is specified by the optional attributes "variable", "key" and "profile". This key is what the the cached data depends on. If none of the attributes are used, the tag will have a single cache entry that always matches.

Note!

It is easy to create huge amounts of cached values if the cache parameters are chosen badly. E.g. to depend on the contents of the form scope is typically only acceptable when combined with a fairly short cache time, since it's otherwise easy to fill up the memory on the server simply by making many requests with random variables.

Shared caches

The cache can be shared between all <cache> tags with identical content, which is typically useful in <cache> tags used in templates included into many pages. The drawback is that cache entries stick around when the <cache> tags change in the RXML source, and that the cache cannot be persistent (see below). Only shared caches have any effect if the RXML pages aren't compiled and cached as p-code.

If the cache isn't shared, and the page is compiled to p-code which is saved persistently then the produced cache entries can also be saved persistently. See the "persistent-cache" attribute for more details.

Note!

For non-shared caches, this tag depends on the caching in the RXML parser to work properly, since the cache is associated with the specific tag instance in the compiled RXML code. I.e. there must be some sort of cache on the top level that can associate the RXML source to an old p-code entry before the cache in this tag can have any effect. E.g. if the RXML parser module in WebServer is used, you have to make sure page caching is turned on in it. So if you don't get cache hits when you think there should be, the cache miss might not be in this tag but instead in the top level cache that maps the RXML source to p-code.

Also note that non-shared timeout caches are only effective if the p-code is cached in RAM. If it should work for p-code that is cached on disk but not in RAM, you need to add the attribute "persistent-cache=yes".

Note to Roxen CMS (a.k.a. SiteBuilder) users: The RXML parser module in WebServer is not used by Roxen CMS. See the CMS documentation for details about how to control RXML p-code caching.

Cache static tags

Note!

Note that this is only applicable if the compatibility level is set to 2.5 or higher.

Some common tags, e.g. <if> and <emit>, are "cache static". That means that they are cached even though there are nested <cache> tag(s). That can be done since they simply let their content pass through (repeated zero or more times).

Cache static tags are always evaluated when the enclosing <cache> generates a new entry. Other tags are evaluated when the entry is used, providing they contain or might contain nested <cache> or <nocache>. This can give side effects; consider this example:

<cache>
  <registered-user>
    <nocache>Your name is &registered-user.name;</nocache>
  </registered-user>
</cache>

Assume the tag <registered-user> is a custom tag that ignores its content whenever the user isn't registered. If it isn't cache static, the nested <nocache> tag causes it to stay unevaluated in the enclosing cache, and the test of the user is therefore kept dynamic. If it on the other hand is cache static, that test is cached and the cache entry will either contain the <nocache> block and a cached assignment to &registered-user.name;, or none of the content inside <registered-user>. The dependencies of the outer cache must then include the user for it to work correctly.

Because of this, it's important to know whether a tag is cache static or not, and it's noted in the doc for all such tags.

Compatibility

If the compatibility level of the site is lower than 2.2 and there is no "variable" or "profile" attribute, the cache depends on the contents of the form scope and the path of the current page (i.e. &page.path;). This is often a bad policy since it's easy for a client to generate many cache entries.

None of the standard RXML tags are cache static if the compatibility level is 2.4 or lower.

Attributes

variable="string"

This is a comma-separated list of variables and scopes that the cache should depend on. The value can be an empty string, which is useful to only disable the default dependencies in compatibility mode.

Since it's important to keep down the size of the cache, this should typically be kept to only a few variables with a limited set of possible values, or else the cache should have a timeout.

key="string"

Use the value of this attribute directly in the key. This attribute mainly exist for compatibility; it's better to use the "variable" attribute instead.

It is an error to use "key" together with "propagate", since it wouldn't do what you'd expect: The value for "key" would not be reevaluated when an entry is chosen from the cache, since the nested, propagating <cache> isn't reached at all then.

profile="string"

A comma-separated list to choose one or more profiles from a set of preconfigured cache profiles. Which cache profiles are available depends on the RXML parser module in use; the standard RXML parser currently has none.

shared

Share the cache between different instances of the <cache> with identical content, wherever they may appear on this page or some other in the same server. See the tag description for details about shared caches.

persistent-cache="{yes, no}"

If the value is "yes" then the cache entries are saved persistently, providing the RXML p-code is saved. If it's "no" then the cache entries are not saved. If it's left out then the default is to save if there's no timeout on the cache, otherwise not. This attribute has no effect if the "shared" attribute is used; shared caches can not be saved persistently.

nocache

Do not cache the content in any way. Typically useful to disable caching of a section inside another cache tag.

propagate

Propagate the cache dependencies to the surrounding <cache> tag, if there is any. Useful to locally add dependencies to a cache without introducing a new cache level. If there is no surrounding <cache> tag, this attribute is ignored.

Note that only the dependencies are propagated, i.e. the settings in the "variable" and "profile" attributes. The other attributes are used only if there's no surrounding <cache> tag.

nohash

If the cache is shared, then the content won't be made part of the cache key. Thus the cache entries can be mixed up with other <cache> tags.

not-post-method

By adding this attribute all HTTP requests using the POST method will be unaffected by the caching. The result will be calculated every time, and the result will not be stored in the cache. The contents of the cache will however remain unaffected by the POST request.

flush-on-no-cache

If this attribute is used the cache will be flushed every time a client sends a pragma no-cache header to the server. These are e.g. sent when shift+reload is pressed in Netscape Navigator.

enable-client-cache

Mark output as cachable by clients. Note that this is likely to introduce overcaching - see the "enable-protocol-cache" attribute for details.

enable-protocol-cache

Mark output as cachable by clients and in server-side protocol cache. Note that this is likely to introduce overcaching since neither the cache key(s) nor any timeout attributes are taken into account by those caches. You can use <set-max-cache> to set a timeout for the protocol cache and for the client-side caching.

years="number"

Add this number of years to the time this entry is valid.

months="number"

Add this number of months to the time this entry is valid.

weeks="number"

Add this number of weeks to the time this entry is valid.

days="number"

Add this number of days to the time this entry is valid.

hours="number"

Add this number of hours to the time this entry is valid.

beats="number"

Add this number of beats to the time this entry is valid.

minutes="number"

Add this number of minutes to the time this entry is valid.

seconds="number"

Add this number of seconds to the time this entry is valid.