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.

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.

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;
};

        

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 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:

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.

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.