iscache Element

Syntax

<iscache 
  status = "on" 
  type   = "relative" | "daily"
  hour   = integer_duration_hr 
  minute = integer_duration_min 
  varyby = "price_promotion"
  if     = boolean_expression />

Attributes

status

Allowed data types: string

Allowed values:

“on” (default)
“off” (deprecated)

The status="off" attribute setting, which explicitly disables page caching, is deprecated. To disable page caching, you can now just omit the <iscache/> element.

If you specify <iscache status="off"/>, the system writes messages to the deprecation log. The messages warn you about the deprecated usage and show the code location for each occurrence. Also, if you set status="off", either in the template or in one of its included templates, you can’t re-enable page caching.

Disabling page caching by setting status="off" can hurt performance, because the server must fetch a new page for each request. If you have a situation where you must disable caching, we recommend using the if attribute of the iscache element. For example, you can disable caching to allow personalization for an individual shopper.

Before <iscache status="off"/> was deprecated, you had to set <iscache status="on"/> to enable page caching. Now, just including an <iscache/> element in your template implicitly enables page caching, so you no longer have to set the status attribute.

type

Allowed data types: string

Allowed values:

"relative"
"daily"

The value “relative” lets you specify a time period, in minutes and hours, after which the page is removed from the cache.

The value “daily” lets you set a specific time when the page is removed from the cache. When specifying time, the 24-hour clock is used. Therefore, 0 is equal to midnight, 1 is equal to 1:00 AM, 2 is equal to 2:00 AM, up to 2359, which is equal to 11:59 PM. The time zone used is GMT.

Note: You must provide either the type or the varyby attribute. If you omit both, the iscache element is invalid and an exception is thrown.

hour

Allowed data types: integer, integer expression

Allowed values:

If you set the type attribute to “daily,” 0—23.
If you set the type attribute “relative,” 0—unlimited.

Default values: If you specify the type attribute, the default is 0. If you specify the varyby attribute and omit the type attribute, the default is the next hour.

Provides the hour value for the time when cache expires daily (type="daily"), or the number of hours from current time when cache expires relatively (type="relative"). Combined with the value of minute attribute.

minute

Allowed data types: integer, integer expression.

Allowed values:

If you set the type attribute to "daily," 0—59.
If you set the type attribute to "relative," 0—unlimited.

Default values: If you specify the type attribute, the default is 0. If you specify the varyby attribute and omit the type attribute, the default is a random value 0–15 minutes (randomized with precision to seconds).

The minute attribute can specify a minute value for the time when the cache expires daily (type="daily"). The minute attribute can also specify the number of minutes from the current time when cache expires relatively (type="relative"). The value of the minute attribute is combined with the value of hour attribute.

varyby

Allowed data types: string

Allowed values: "price_promotion"

The varyby attribute lets you mark a page as personalized. When a page is marked as personalized, Salesforce B2C Commerce uses additional parameters besides the URL string to uniquely identify the page cache. The web adapter stores the different variationss of the page in the cache, and then delivers the correct version to the shopper based on these additional parameters.

For the personalized cache to work properly, the following must be different within the context of the page:

The complete set of active promotions.
The complete set of active product sorting rules.
The complete set of applicable price books.
The complete set of active ABTest Groups.

You can personalize a page by means other than price books, promotions, product sorting rules, or A/B test groups. If you do this type of personalization, don’t cache the page, because some shoppers can see incorrect variations of the page. To turn off caching for these pages, you can set the if attribute. Alternatively, if you link this custom personalization code to promotion objects, for example, then you can use varyby="price_promotion" because the set of active promotions is different.

For performance reasons, only use the varyby property if the page has different variations based on the additional parameters described previously. Otherwise, you can degrade performance unnecessarily because multiple identical copies of the same page are stored in the cache, resulting in cache fragmentation.

A page is either personalized or not personalized. If a page contains multiple <iscache/> elements, some with the varyby attribute set and some with this attribute not set, the entire page is treated as personalized.

if

Allowed data types: boolean expression

Like the deprecated status="off" attribute setting, the if attribute lets you turn off caching, but it does so based on a condition. You can use this attribute to provide personalization for individual shoppers—for example, when implementing Commerce Cloud Einstein Predictive Sort. However, when the if condition evaluates to false, page caching is disabled. Therefore, we recommend you use the if attribute only for pages with little or no interaction with persisted objects. Otherwise, using this attribute can severely degrade performance. If you can use the varyby attribute instead, we recommend using it for personalization instead of the if attribute.

Purpose

Cached pages are returned to the storefront quickly. A cached page is treated more like a static page, and less like a dynamically generated page.

After a page is cached, the system bypasses the controller that renders the page. Consequently, the server doesn’t process any isml templates, and the cached content of the page is delivered to the shopper almost instantaneously.

Note: Sometimes, you can’t cache a page, or you don’t want to cache a page. For example, you generally don’t want to cache pages that contain shopper-specific data, such as address or basket information. For more information, see Page Caching.

The first time a page is requested, the server dynamically generates the page. After the page is generated, it can be cached. If you want a storefront page to be cached, you must include the <iscache> element in the template. Alternatively, in the controller that renders the page, you can use one of the setExpires methods of the Response Script API class.

The <iscache> element lets you specify when the cached page expires from the cache. For example, you can expire the cached page after a fixed period.

The <iscache> element can be located anywhere in the template, but we recommend that you place the element as near as possible to the beginning of the template.

If you add multiple <iscache> elements in your template (or in locally included templates), one element takes precedence over the others. If an element turns caching off, it’s given precedence over the other elements. Otherwise, the element with the shortest cache time is given precedence. In general, when there are multiple <iscache> elements, the most restrictive one wins.

Note:

Consider the following when using page caching:

When caching pages, don't use session information in the same template or in locally included templates. Session information includes shopper login status, basket contents, and so on. Session information is specific to each individual shopper. If session information gets cached and is mistakenly displayed to other shoppers, unexpected results can occur.
When using templates as decorators (via the isdecorate element), display session information only in a remotely included, non-cached request. Otherwise, a template that uses the decorator can mistakenly apply caching to the decorator’s session data as well as its own. If session information gets cached and is mistakenly displayed to other shoppers, unexpected results can occur.
If you put an <iscache> element in a locally included template, the element affects the caching of the whole page that is being produced.
If you must display dynamic data, reduce the logic to the minimum needed and avoid unnecessary operations with persistent objects. Cache everything you can, leaving only small dynamic snippets on frequently visited pages.

Relative Caching Examples

The following lines of code are equivalent. Each line causes the resulting page to expire from the cache after 150 minutes:

<iscache type="relative" hour="2" minute="30">

<iscache type="relative" hour="1" minute="90">

<iscache type="relative" minute="150">

Daily Caching Examples

The following line of code causes the resulting page to expire from the cache every day at midnight (0:00 AM):

<iscache type="daily">

The following line of code causes the resulting page to expire from the cache every day at 0630 hours (6:30 AM):

<iscache type="daily" hour="6" minute="30">

The following line of code causes the resulting page to expire from the cache every day at 2330 hours (11:30 PM):

<iscache type="daily" hour="23" minute="30">

If Attribute Example

The following line of code causes the resulting page to turn off caching, allowing for the proper display of predictive sorting results:

<iscache hour="2" varyby="price_promotion" if="${!searchModel.isPersonalizedSort()}"/>

When used with the if attribute, the expression {!searchModel.isPersonalizedSort()} lets you control whether a page is cached. Use this technique with Predictive Sort to control the caching of predictive pages at the template level.

When the if attribute is used in this way, search requests that use a sorting rule with Predictive Sort are no longer cached. Caching is activated when the expression evaluates to true (the sorting isn’t personalized). Caching is deactivated when the expression evaluates to false (the sorting is personalized). If the expression evaluates to a non-boolean value, or if you try passing a value instead of an expression, an error is thrown.

Varyby Example

The following line of code is suitable for a search result page:

<iscache type="relative" minute="30" varyby="price_promotion"/>

The search result page depends on availability information that can change over time, so we set the caching time to 30 minutes. The page also shows price and promotion information, which can differ by shopper. To instruct B2C Commerce to account for this possibility, we added varyby="price_promotion". With this added element, a cached page appears if the shopper has the same eligibility for prices and promotions.

The following line of code causes the resulting page to expire from the cache in a random interval. The random interval falls between 1 second and 15 minutes after the beginning of the next hour.

<iscache varyby="price_promotion"/>