iscache Element
Controls page caching to improve the performance of your storefront.
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 setstatus="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 theif
attribute of theiscache
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 thestatus
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.
<doc-content-callout header="Note" variant="note"> <div><p>You must provide either the <code>type</code> or the <code>varyby</code> attribute. If you omit both, the <code>iscache</code> element is invalid and an exception is thrown.</p></div> </doc-content-callout>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 thevaryby
attribute and omit thetype
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.- If you set the
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 thevaryby
attribute and omit thetype
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"
). Theminute
attribute can also specify the number of minutes from the current time when cache expires relatively (type="relative"
). The value of theminute
attribute is combined with the value ofhour
attribute.- If you set the
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 variations 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 usevaryby="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, theif
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 theif
condition evaluates to false, page caching is disabled. Therefore, we recommend you use theif
attribute only for pages with little or no interaction with persisted objects. Otherwise, using this attribute can severely degrade performance. If you can use thevaryby
attribute instead, we recommend using it for personalization instead of theif
attribute.
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.
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.
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.
- In cases where
<isscript>
blocks finish with exceptions, or database exceptions occur, the cache time is limited to 5 minutes. Exceptions from script expressions within ISML are excluded. To prevent exceptions, and improve and ensure performance, review logs and clean up your code.
The following lines of code are equivalent. Each line causes the resulting page to expire from the cache after 150 minutes:
The following line of code causes the resulting page to expire from the cache every day at midnight (0:00 AM):
The following line of code causes the resulting page to expire from the cache every day at 0630 hours (6:30 AM):
The following line of code causes the resulting page to expire from the cache every day at 2330 hours (11:30 PM):
The following line of code causes the resulting page to turn off caching, allowing for the proper display of predictive sorting results:
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.
The following line of code is suitable for a search result page:
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.