Connector for Salesforce Commerce Cloud Manual / Version 2406.1
Table Of Contents
This section discusses the ability of using the Salesforce Page Caching for CMS fragments.
In general, the CMS fragments are added to the Salesforce Page Cache
just like the parts that render the shop itself. Since this cache operates on the granularity
of Salesforce controllers, usually several CMS fragments are cached together if they weren't
included with a islcincludeRemote
tag for themselves.
After a fragment is retrieved from the CMS the Connector for Salesforce Commerce Cloud can set cache directives to control
the Salesforce Page Caching. This is essentially a setExpires
call on the
response. Salesforce Commerce automatically evaluates all cache times for a page
(or a certain controller output) and will choose the minimum time to cache the page.
With the Salesforce Storefront Developer Tools you can see the
current effective cache times per controller output. In this example, several homepage fragments
are put together to one cacheable page. The responsible controller is Home-Show
.
Every CMS fragment within this cacheable unit can also influence the cache time by setting the minimal value. There are two possible situations that can be handled differently, either if the CMS fragment was loaded successfully or if an error has occurred. For both cases, there is a configuration setting (see Table 5.4, “ Cache settings ”) in the CoreMedia Custom Site Preferences that controls the CMS fragment caching. You can add them in the Salesforce Commerce Business Manager.
cmPageCacheOnErrorTTL
| |
Default |
Disabled |
Description |
If an error occurs, the fragment should probably not be cached for a long time. By default, the expiration time is not set. CoreMedia recommends entering a moderate value here, for example, 60 seconds, to avoid flooding the server that is in trouble with too many requests. |
cmPageCacheDefaultTTL
| |
Default |
Disabled |
Description |
If a fragment could be loaded successfully, you can define the expiration time. By default, no expiration time is set. This value should be aligned with the expected frequency of page changes and the requirement for the topicality of the site. CoreMedia recommends a higher value, for example, 3600 seconds. |
Table 5.4. Cache settings
Caution
Please note that using the cache TTL for CMS fragments affects the enclosing page. And please also note that
page caching is switched off, by default, in Salesforce Commerce. That means if the surrounding template
doesn't already use page caching for itself, a setExpires()
call on the response would enable the
caching of the whole page/fragment. If such a page must not be cached (for example, to display the most current
information), caching can be disabled in individual cases as described below.
Disabling caching on demand
Note
The following functionality is only available with CoreMedia Cartridge for Salesforce version 3.4.x and higher.
The standard routine looks for a custom request attribute that prevents fragment caching
(setExpires()
will not be called).
If this is desired, then set the request attribute request.custom.shouldBeCached
to
false
.
If this simple logic is not sufficient for your demands, you can also overwrite
it in your own cartridge that is placed in front of the int_coremedia
cartridge in the path.
To do this, create a script cmCacheControl.js
in the directory scripts
and implement your own shouldBeCached
function.
/** * Function that can be overwritten in customer projects to decide if * caching is enabled for a fragment. If page caching is generally * switched off and outer, surrounding templates must not be cached, * it would be counterproductive if the include of an CMS fragment * enables the caching (response.setExpires()). * The default implementation evaluates a custom request attribute * 'shouldBeCached'. If not found it returns true. * Note, this only applies if CoreMedia fragment caching is switched on. * * @param {string} fragmentUrl - the fragment url * @param {Object} request - the current request * @returns {boolean} true if caching is enabled */ exports.shouldBeCached = function (fragmentUrl, request) { var enabled = request.custom.shouldBeCached; if (enabled === null) { enabled = true; } if (enabled) { Logger.debug('caching is enabled for "' + fragmentUrl + '"'); } else { Logger.debug('caching is disabled for "' + fragmentUrl + '"'); } return enabled; };
Example 5.4. scripts/cmCacheControl.js example
Let the CMS control the fragment caching
Note
The following functionality is only available with CoreMedia Cartridge for Salesforce version 3.4.x and higher.
Instead of configuring the expiry times in the Salesforce system, you can also use the expiry information sent by the
CMS response, either as HTTP response header or within the JSON structure as part of the prefetch (see
Section 5.6, “Prefetch Fragments to Minimize CMS Requests”). For example, if the CMS sends the seconds for a day as max-age
value in the Cache-Control
header, these seconds are converted into a date and set as expiry date on
the response.
When CMS expiry information is not used
The CMS information will not be used, when the
cmPageCacheDefaultTTL
custom site setting in the CoreMedia Custom Site Preferences is set to "-1" or when caching is disabled by theshouldBeCached
function.The CMS information will also not be used when the value configured with the CoreMedia Custom Site Preferences property
cmPageCacheDefaultTTL
is smaller than the value send by the CMS.
To control the Salesforce page caching CoreMedia provides the script cmCacheControl.js
.
It supports two variants of HTTP headers to extract the expiry information from the CMS response:
Standard procedure for HTTP 1.1
The script tries to read the standard headers from the response to determine an expiry date. First of all it looks for a
Cache-Control
header with amax-age
value in seconds. A givenAge
header is also considered (and subtracted if given).Procedure for HTTP 1.0
The script looks for an
Expiry
header together with aDate
header (and subtracts it if given).
Depending on the success of the fragment request, the script contains two methods (see Table 5.5, “ Cache Control methods ”), which decide which expiry to set in the Salesforce response.
setPageCacheExpiryOnSuccess
| |
Description |
Implements the cache control in case of success (no error has been occurred when getting the fragment
from the CMS). Either the expiry date is already determined by the value found in the prefetch response
or it is read from existing headers
(
Note, this method is only called if the |
setPageCacheExpiryOnError
| |
Description |
Implements the cache control in case of an error (when getting the fragment from the CMS).
By default the configured
Note, this method is only called if the |
Table 5.5. Cache Control methods
This default behavior can easily be overwritten and customized in your own cartridge. It just has to be set in the cartridge path in front of this script.