iscache Element
Controls page caching to improve the performance of your storefront.
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 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.
Note: You must provide either thetype
or thevaryby
attribute. If you omit both, theiscache
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 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 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 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.
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.
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.
<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.
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"/>