close

Filter

Connector for Salesforce Commerce Cloud Manual / Version 2304

Table Of Contents

5.5 Using Salesforce Page Cache for CMS Fragments

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.

Storefront Cache Information

Figure 5.9. Storefront Cache Information


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

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

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

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.

Note

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 the shouldBeCached 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 a max-age value in seconds. A given Age header is also considered (and subtracted if given).

  • Procedure for HTTP 1.0

    The script looks for an Expiry header together with a Date 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 (Cache-Control/Age headers or Expires/Date headers). When the configured Salesforce default time (cmPageCacheDefaultTTL) is even shorter, then the default is used.

Note, this method is only called if the cmPageCacheDefaultTTL value is set (greater than -1) and the shouldBeCached method evaluates to true.

setPageCacheExpiryOnError
Description

Implements the cache control in case of an error (when getting the fragment from the CMS). By default the configured cmPageCacheOnErrorTTL value is used to set on response.

Note, this method is only called if the cmPageCacheOnErrorTTL value is set (greater than -1) and the shouldBeCached method evaluates to true.

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.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.