sfcc-dev-mcp 1.0.15 → 1.0.19

package/docs/isml/iscache.md

@@ -0,0 +1,802 @@
+# ISML iscache Element
+
+## Overview
+
+The `<iscache>` element controls page caching to dramatically improve storefront performance. By caching pages, the server bypasses dynamic page generation and delivers pre-rendered content almost instantaneously. This element allows you to specify cache expiration strategies, personalization requirements, and conditional caching based on business rules.
+
+**Performance Impact:** Cached pages are treated like static content, eliminating controller execution and template processing for subsequent requests.
+
+## Syntax
+
+```isml
+<iscache
+  status = "on"                      // optional (default: "on")
+  type   = "relative" | "daily"      // optional (required if no varyby)
+  hour   = integer_duration_hr       // optional
+  minute = integer_duration_min      // optional
+  varyby = "price_promotion"         // optional (required if no type)
+  if     = boolean_expression        // optional
+/>
+```
+
+## Attributes
+
+### status
+
+**Type:** String  
+**Allowed Values:** `"on"` (default), `"off"` (deprecated)  
+**Optional:** Yes
+
+Controls whether page caching is enabled or disabled.
+
+⚠️ **DEPRECATED:** `status="off"` is deprecated. To disable caching, simply omit the `<iscache>` element or use the `if` attribute for conditional disabling.
+
+**Important:**
+- Just including `<iscache/>` implicitly enables caching (no need to set `status="on"`)
+- If `status="off"` is set anywhere (template or includes), caching cannot be re-enabled
+- Using `status="off"` writes deprecation warnings to logs
+- Disabling caching hurts performance—use the `if` attribute instead for conditional control
+
+```isml
+<!-- Modern: Caching enabled (recommended) -->
+<iscache type="relative" hour="1"/>
+
+<!-- Deprecated: Don't use status="off" -->
+<iscache status="off"/>  <!-- DEPRECATED -->
+
+<!-- Instead: Use if attribute for conditional caching -->
+<iscache type="relative" hour="1" if="${!pdict.isPersonalized}"/>
+```
+
+### type
+
+**Type:** String  
+**Allowed Values:** `"relative"`, `"daily"`  
+**Required:** Yes (unless `varyby` is specified)
+
+Specifies the caching strategy—either relative to current time or at a specific daily time.
+
+**`"relative"`**: Cache expires after a specified duration from the time the page was cached.
+- Use `hour` and `minute` to specify duration
+- Example: Cache for 2 hours and 30 minutes
+
+**`"daily"`**: Cache expires at a specific time each day (GMT timezone, 24-hour format).
+- Use `hour` and `minute` to specify time (0:00 - 23:59)
+- Example: Expire at 6:30 AM GMT daily
+
+```isml
+<!-- Relative: Cache for 2 hours -->
+<iscache type="relative" hour="2"/>
+
+<!-- Daily: Expire at 6:30 AM GMT every day -->
+<iscache type="daily" hour="6" minute="30"/>
+```
+
+### hour
+
+**Type:** Integer or Integer Expression  
+**Allowed Values:**
+- `type="daily"`: 0–23 (24-hour format)
+- `type="relative"`: 0–unlimited
+**Default:** 0 (if `type` specified), next hour (if only `varyby` specified)
+
+For `type="daily"`: The hour of day (GMT) when cache expires.  
+For `type="relative"`: Number of hours from current time when cache expires.
+
+```isml
+<!-- Daily: Expire at 14:00 (2:00 PM) GMT -->
+<iscache type="daily" hour="14"/>
+
+<!-- Relative: Cache for 3 hours -->
+<iscache type="relative" hour="3"/>
+
+<!-- Expression: Dynamic hour value -->
+<iscache type="relative" hour="${pdict.cacheHours}"/>
+```
+
+### minute
+
+**Type:** Integer or Integer Expression  
+**Allowed Values:**
+- `type="daily"`: 0–59
+- `type="relative"`: 0–unlimited
+**Default:** 0 (if `type` specified), random 0–15 minutes (if only `varyby` specified)
+
+For `type="daily"`: The minute of the hour when cache expires.  
+For `type="relative"`: Number of minutes from current time when cache expires.
+
+```isml
+<!-- Daily: Expire at 6:30 AM GMT -->
+<iscache type="daily" hour="6" minute="30"/>
+
+<!-- Relative: Cache for 90 minutes -->
+<iscache type="relative" minute="90"/>
+
+<!-- Relative: Cache for 2 hours 30 minutes -->
+<iscache type="relative" hour="2" minute="30"/>
+
+<!-- Expression: Dynamic minute value -->
+<iscache type="relative" minute="${pdict.cacheMinutes}"/>
+```
+
+### varyby
+
+**Type:** String  
+**Allowed Values:** `"price_promotion"`  
+**Required:** Yes (unless `type` is specified)
+
+Marks a page as personalized, instructing Commerce Cloud to cache different variations based on:
+- Complete set of active promotions
+- Complete set of active product sorting rules
+- Complete set of applicable price books
+- Complete set of active A/B test groups
+
+**How it works:**
+- Web adapter stores different page variations in cache
+- Correct version delivered to shopper based on their promotion/price/sorting/AB test context
+- Multiple shoppers with same context receive same cached page
+
+⚠️ **Performance Warning:** Only use `varyby` when pages actually vary by these parameters. Unnecessary use causes cache fragmentation (multiple identical copies stored), degrading performance.
+
+```isml
+<!-- Personalized search results (vary by price/promotion) -->
+<iscache type="relative" minute="30" varyby="price_promotion"/>
+
+<!-- Category page with promotional pricing -->
+<iscache type="relative" hour="2" varyby="price_promotion"/>
+
+<!-- Only varyby (random expiration next hour) -->
+<iscache varyby="price_promotion"/>
+```
+
+**Page Personalization Rule:** If any `<iscache>` element on a page has `varyby` set, the **entire page** is treated as personalized (even if other `<iscache>` elements don't have `varyby`).
+
+### if
+
+**Type:** Boolean Expression  
+**Optional:** Yes
+
+Conditionally disables caching based on an expression. When the expression evaluates to `false`, page caching is disabled.
+
+⚠️ **Performance Warning:** Disabling caching significantly impacts performance. Use sparingly and only on pages with minimal persistent object interaction.
+
+**Use Cases:**
+- Einstein Predictive Sort (personalized sorting)
+- Individual shopper personalization
+- Dynamic content that can't use `varyby`
+
+**Recommendation:** If possible, use `varyby="price_promotion"` instead of the `if` attribute for better performance.
+
+```isml
+<!-- Disable caching for personalized sort -->
+<iscache hour="2" varyby="price_promotion" if="${!searchModel.isPersonalizedSort()}"/>
+
+<!-- Cache only for non-logged-in users -->
+<iscache type="relative" hour="1" if="${!customer.authenticated}"/>
+
+<!-- Cache unless basket has items -->
+<iscache type="relative" minute="30" if="${empty(pdict.Basket.productLineItems)}"/>
+```
+
+**Expression Requirements:**
+- Must evaluate to boolean (`true` or `false`)
+- Passing a non-boolean value throws an error
+- Passing a value instead of expression throws an error
+
+## Purpose and Behavior
+
+### Performance Benefits
+
+**Without Cache:**
+1. Request arrives
+2. Controller executes
+3. ISML templates processed
+4. Dynamic page generated
+5. Response sent
+
+**With Cache:**
+1. Request arrives
+2. Cached page delivered immediately (controller and templates bypassed)
+
+**Result:** Near-instantaneous page delivery, significantly reduced server load.
+
+### First Request Flow
+
+1. **Initial Request:** Page not in cache
+2. **Dynamic Generation:** Server executes controller and processes templates
+3. **Cache Storage:** Generated page stored in cache with expiration settings
+4. **Subsequent Requests:** Cached page delivered until expiration
+
+### Cache Expiration
+
+When cached page expires:
+- Next request triggers dynamic generation
+- Newly generated page replaces old cache entry
+- Cache cycle continues
+
+## Common Use Cases
+
+### Homepage (Daily Expiration)
+
+```isml
+<!-- homepage.isml -->
+<iscache type="daily" hour="0" minute="0"/>
+
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Welcome to Our Store</title>
+</head>
+<body>
+    <h1>Featured Products</h1>
+    <!-- Static or rarely changing content -->
+</body>
+</html>
+```
+
+**Rationale:** Homepage changes once daily (new promotions, featured products), expires at midnight.
+
+### Product Listing Page (Relative Expiration)
+
+```isml
+<!-- search/productListing.isml -->
+<iscache type="relative" hour="1"/>
+
+<div class="product-listing">
+    <h2>Search Results</h2>
+    <isloop items="${pdict.products}" var="product">
+        <div class="product-tile">
+            <h3>${product.name}</h3>
+            <span>${product.price}</span>
+        </div>
+    </isloop>
+</div>
+```
+
+**Rationale:** Product availability and pricing can change; cache for 1 hour to balance freshness and performance.
+
+### Search Results with Personalization
+
+```isml
+<!-- search/searchResults.isml -->
+<iscache type="relative" minute="30" varyby="price_promotion"/>
+
+<div class="search-results">
+    <isloop items="${pdict.searchResults}" var="result">
+        <div class="result-item">
+            <h4>${result.productName}</h4>
+            <span class="price">${result.price}</span>
+            <span class="promo">${result.promotionText}</span>
+        </div>
+    </isloop>
+</div>
+```
+
+**Rationale:** Prices and promotions vary by customer segment; use `varyby` to cache variations.
+
+### Category Landing Page
+
+```isml
+<!-- category/categoryLanding.isml -->
+<iscache type="relative" hour="2" varyby="price_promotion"/>
+
+<h1>${pdict.category.displayName}</h1>
+<p>${pdict.category.description}</p>
+
+<!-- Category navigation and products -->
+```
+
+**Rationale:** Categories show promotional content and varied pricing; cache for 2 hours with personalization.
+
+### Product Detail Page (Non-Personalized)
+
+```isml
+<!-- product/productDetails.isml -->
+<iscache type="relative" hour="1"/>
+
+<div class="product-detail">
+    <h1>${pdict.Product.name}</h1>
+    <p>${pdict.Product.longDescription}</p>
+    <span class="price">${pdict.Product.price}</span>
+    
+    <!-- Product details -->
+</div>
+```
+
+**Rationale:** Product details are mostly static; cache for 1 hour to ensure price/availability freshness.
+
+### Content Page (Long Cache)
+
+```isml
+<!-- content/aboutUs.isml -->
+<iscache type="daily" hour="3"/>
+
+<div class="content-page">
+    <h1>About Us</h1>
+    <p>Our company story...</p>
+</div>
+```
+
+**Rationale:** Static content changes rarely; cache until 3:00 AM GMT daily.
+
+### Einstein Predictive Sort
+
+```isml
+<!-- search/searchResults.isml -->
+<iscache hour="2" varyby="price_promotion" if="${!searchModel.isPersonalizedSort()}"/>
+
+<div class="search-results">
+    <!-- Search results with optional personalized sorting -->
+</div>
+```
+
+**Rationale:** Disable caching when Predictive Sort is active (personalized); otherwise cache for 2 hours.
+
+### Conditional Caching (Logged-In Users)
+
+```isml
+<!-- homepage.isml -->
+<iscache type="relative" hour="1" if="${!customer.authenticated}"/>
+
+<div class="homepage">
+    <!-- Content that's safe to cache for anonymous users only -->
+</div>
+```
+
+**Rationale:** Cache for anonymous users, disable for logged-in users who see personalized content.
+
+## Best Practices
+
+1. **Place at Template Beginning:**
+   ```isml
+   <!-- Good: Near the top -->
+   <iscache type="relative" hour="1"/>
+   
+   <!DOCTYPE html>
+   <html>
+   <!-- ... -->
+   ```
+
+2. **Never Cache Session-Specific Pages:**
+   ```isml
+   <!-- Bad: Caching basket page (session-specific) -->
+   <iscache type="relative" hour="1"/>  <!-- DON'T DO THIS -->
+   <div class="basket">
+       ${pdict.Basket.totalGrossPrice}
+   </div>
+   
+   <!-- Good: No caching for basket -->
+   <div class="basket">
+       ${pdict.Basket.totalGrossPrice}
+   </div>
+   ```
+
+3. **Use varyby Only When Needed:**
+   ```isml
+   <!-- Good: Page actually varies by price/promotion -->
+   <iscache type="relative" hour="1" varyby="price_promotion"/>
+   
+   <!-- Bad: Unnecessary varyby (causes cache fragmentation) -->
+   <iscache type="relative" hour="1" varyby="price_promotion"/>
+   <!-- On a page with no prices or promotions -->
+   ```
+
+4. **Avoid status="off" (Use if Instead):**
+   ```isml
+   <!-- Bad: Deprecated -->
+   <iscache status="off"/>
+   
+   <!-- Good: Conditional caching -->
+   <iscache type="relative" hour="1" if="${!pdict.requiresFreshData}"/>
+   ```
+
+5. **Choose Appropriate Cache Duration:**
+   ```isml
+   <!-- Static content: Long cache (24 hours or daily) -->
+   <iscache type="daily"/>
+   
+   <!-- Dynamic content: Short cache (15-60 minutes) -->
+   <iscache type="relative" minute="30"/>
+   
+   <!-- Frequently changing: Very short cache (5-15 minutes) -->
+   <iscache type="relative" minute="10"/>
+   ```
+
+6. **Understand Precedence in Multiple Elements:**
+   ```isml
+   <!-- Most restrictive wins -->
+   <iscache type="relative" hour="2"/>  <!-- 2 hours -->
+   <isinclude template="components/header"/>  <!-- Contains: hour="1" -->
+   
+   <!-- Result: 1 hour cache (shortest time wins) -->
+   ```
+
+7. **Use Expressions for Dynamic Configuration:**
+   ```isml
+   <!-- Good: Configurable cache time -->
+   <iscache type="relative" hour="${pdict.cacheConfig.hours}"/>
+   
+   <!-- Or from site preferences -->
+   <isscript>
+       var Site = require('dw/system/Site');
+       var cacheHours = Site.current.getCustomPreferenceValue('categoryPageCacheHours') || 1;
+   </isscript>
+   <iscache type="relative" hour="${cacheHours}"/>
+   ```
+
+## Pages That Should NOT Be Cached
+
+❌ **Never cache these page types:**
+
+1. **Cart/Basket Pages**
+   ```isml
+   <!-- NO caching -->
+   <div class="cart">
+       ${pdict.Basket.totalGrossPrice}
+   </div>
+   ```
+
+2. **Checkout Pages**
+   ```isml
+   <!-- NO caching -->
+   <div class="checkout">
+       <!-- Billing, shipping, payment info -->
+   </div>
+   ```
+
+3. **Account Pages**
+   ```isml
+   <!-- NO caching -->
+   <div class="account">
+       ${customer.profile.firstName}
+       <!-- Customer-specific information -->
+   </div>
+   ```
+
+4. **Order Confirmation**
+   ```isml
+   <!-- NO caching -->
+   <div class="order-confirmation">
+       Order ${pdict.Order.orderNo}
+   </div>
+   ```
+
+5. **Form Submission Results**
+   ```isml
+   <!-- NO caching -->
+   <div class="form-result">
+       <!-- Dynamic response to user action -->
+   </div>
+   ```
+
+## Cache Precedence Rules
+
+When multiple `<iscache>` elements exist (in template and includes):
+
+### Rule 1: Caching Disabled Wins
+
+```isml
+<!-- main.isml -->
+<iscache type="relative" hour="2"/>
+
+<!-- include.isml (included in main.isml) -->
+<iscache status="off"/>  <!-- or if="${false}" -->
+
+<!-- Result: Caching DISABLED (off/false takes precedence) -->
+```
+
+### Rule 2: Shortest Cache Time Wins
+
+```isml
+<!-- main.isml -->
+<iscache type="relative" hour="3"/>
+
+<!-- include1.isml -->
+<iscache type="relative" hour="1"/>
+
+<!-- include2.isml -->
+<iscache type="relative" minute="30"/>
+
+<!-- Result: 30 minutes (shortest time) -->
+```
+
+### Rule 3: Personalized Wins
+
+```isml
+<!-- main.isml -->
+<iscache type="relative" hour="2"/>
+
+<!-- include.isml -->
+<iscache type="relative" hour="2" varyby="price_promotion"/>
+
+<!-- Result: Entire page treated as PERSONALIZED -->
+```
+
+## Template Decorator Considerations
+
+⚠️ **Critical:** When using decorators (`<isdecorate>`), be careful with session information.
+
+```isml
+<!-- decorator.isml (DANGEROUS) -->
+<iscache type="relative" hour="1"/>
+
+<html>
+<head>
+    <title>${pdict.pageTitle}</title>
+</head>
+<body>
+    <!-- Session info in decorator -->
+    <div class="user-greeting">
+        Welcome, ${customer.profile.firstName}!  <!-- DANGEROUS -->
+    </div>
+    
+    <isreplace/>  <!-- Decorated content here -->
+</body>
+</html>
+
+<!-- page.isml (uses decorator) -->
+<isdecorate template="decorator"/>
+<iscache type="relative" hour="2"/>  <!-- Can cache decorator's session data! -->
+
+<div class="content">
+    <!-- Page content -->
+</div>
+```
+
+**Problem:** Decorator's session information gets cached and shown to all users.
+
+**Solution:** Use remote includes for session-specific content:
+
+```isml
+<!-- decorator.isml (SAFE) -->
+<iscache type="relative" hour="1"/>
+
+<html>
+<head>
+    <title>${pdict.pageTitle}</title>
+</head>
+<body>
+    <!-- Remote include for session data (not cached) -->
+    <isinclude url="${URLUtils.url('Page-UserGreeting')}"/>
+    
+    <isreplace/>
+</body>
+</html>
+```
+
+## Relative Caching Examples
+
+```isml
+<!-- All equivalent: 150 minutes (2 hours 30 minutes) -->
+<iscache type="relative" hour="2" minute="30"/>
+<iscache type="relative" hour="1" minute="90"/>
+<iscache type="relative" minute="150"/>
+
+<!-- 1 hour -->
+<iscache type="relative" hour="1"/>
+
+<!-- 30 minutes -->
+<iscache type="relative" minute="30"/>
+
+<!-- 3 hours 45 minutes -->
+<iscache type="relative" hour="3" minute="45"/>
+```
+
+## Daily Caching Examples
+
+```isml
+<!-- Expire at midnight (0:00 AM GMT) -->
+<iscache type="daily"/>
+<iscache type="daily" hour="0"/>
+<iscache type="daily" hour="0" minute="0"/>
+
+<!-- Expire at 6:30 AM GMT -->
+<iscache type="daily" hour="6" minute="30"/>
+
+<!-- Expire at 11:30 PM GMT (23:30) -->
+<iscache type="daily" hour="23" minute="30"/>
+
+<!-- Expire at noon GMT (12:00 PM) -->
+<iscache type="daily" hour="12"/>
+
+<!-- Expire at 3:15 AM GMT -->
+<iscache type="daily" hour="3" minute="15"/>
+```
+
+## varyby Examples
+
+```isml
+<!-- Random expiration 1 second to 15 minutes after next hour -->
+<iscache varyby="price_promotion"/>
+
+<!-- 30-minute cache with personalization -->
+<iscache type="relative" minute="30" varyby="price_promotion"/>
+
+<!-- Daily expiration with personalization -->
+<iscache type="daily" hour="3" varyby="price_promotion"/>
+
+<!-- 2-hour cache with personalization -->
+<iscache type="relative" hour="2" varyby="price_promotion"/>
+```
+
+## if Attribute Examples
+
+```isml
+<!-- Cache unless personalized sort -->
+<iscache hour="2" varyby="price_promotion" if="${!searchModel.isPersonalizedSort()}"/>
+
+<!-- Cache only for anonymous users -->
+<iscache type="relative" hour="1" if="${!customer.authenticated}"/>
+
+<!-- Cache unless basket has items -->
+<iscache type="relative" minute="30" if="${empty(pdict.Basket.productLineItems)}"/>
+
+<!-- Cache unless specific condition -->
+<iscache type="relative" hour="2" if="${!pdict.disableCache}"/>
+
+<!-- Cache during business hours only -->
+<isscript>
+    var now = new Date();
+    var hour = now.getHours();
+    var isBusinessHours = (hour >= 9 && hour < 17);
+</isscript>
+<iscache type="relative" hour="1" if="${isBusinessHours}"/>
+```
+
+## Exception Handling and Cache Limits
+
+⚠️ **Important:** When exceptions occur, cache time is limited to **5 minutes** to prevent caching error states:
+
+**Exceptions that limit cache:**
+- `<isscript>` blocks finish with exceptions
+- Database exceptions
+- Persistent object operation failures
+
+**Excluded:** Exceptions from script expressions within ISML (${...})
+
+**Best Practice:** Review logs and fix exceptions to ensure optimal caching performance.
+
+```isml
+<iscache type="relative" hour="24"/>
+
+<isscript>
+    // If this throws exception, cache limited to 5 minutes
+    var product = ProductMgr.getProduct('INVALID_ID');
+    product.name;  // Throws exception if product is null
+</isscript>
+
+<!-- Cache time: 5 minutes (not 24 hours) due to exception -->
+```
+
+## Performance Guidelines
+
+### Cache Everything Possible
+
+```isml
+<!-- Good: Cache static/semi-static pages -->
+<iscache type="relative" hour="1"/>
+```
+
+### Leave Only Small Dynamic Snippets
+
+```isml
+<!-- Cached page with small dynamic section -->
+<iscache type="relative" hour="2"/>
+
+<div class="page-content">
+    <!-- Cached content -->
+    
+    <!-- Small dynamic snippet (remote include, not cached) -->
+    <isinclude url="${URLUtils.url('Account-MiniCart')}"/>
+</div>
+```
+
+### Minimize Logic in Cached Pages
+
+```isml
+<!-- Bad: Heavy logic in cached template -->
+<iscache type="relative" hour="1"/>
+
+<isscript>
+    // Expensive database operations
+    var products = CustomObjectMgr.queryCustomObjects(...);
+    // Complex calculations
+</isscript>
+
+<!-- Good: Prepare data in controller -->
+<iscache type="relative" hour="1"/>
+
+<isloop items="${pdict.products}" var="product">
+    ${product.name}
+</isloop>
+```
+
+## Debugging and Testing
+
+### Verify Caching is Active
+
+```bash
+# Check response headers
+curl -I https://yoursite.com/page
+
+# Look for:
+# X-IS-Cache-Key: [cache key]
+# X-IS-Cache-Store: [cache store name]
+```
+
+### Test Cache Expiration
+
+1. Load page first time (cache miss)
+2. Load page again (cache hit)
+3. Wait for expiration time
+4. Load page again (cache miss, regenerated)
+
+### Monitor Cache Performance
+
+Check Business Manager:
+- Operations > Site Cache > Cache Statistics
+- Monitor hit rates, miss rates
+- Identify cache fragmentation
+
+## Related Elements
+
+- `<isdecorate>` - Template decorators (be careful with session data)
+- `<isinclude>` - Local includes (affected by page cache)
+- `<isinclude url>` - Remote includes (not cached)
+- `<isscript>` - Script blocks (exceptions limit cache to 5 minutes)
+
+## Response API Alternative
+
+Instead of `<iscache>` in templates, use Response API in controllers:
+
+```javascript
+// Controller
+var Response = require('dw/system/Response');
+
+// Relative expiration
+Response.setExpires(new Date(Date.now() + 3600000)); // 1 hour
+
+// Vary by price/promotion
+Response.setVaryBy('price_promotion');
+```
+
+## Notes
+
+- `<iscache>` can appear anywhere in template (recommended: near beginning)
+- Multiple elements: most restrictive wins
+- Caching disabled anywhere: entire page not cached
+- Personalized anywhere (`varyby`): entire page personalized
+- Session information must not be cached
+- Decorator session data: use remote includes only
+- Exceptions limit cache to 5 minutes
+- Default (no element): page not cached
+- Just including element enables caching (no `status="on"` needed)
+- GMT timezone for daily caching
+- Random 0-15 minute default with `varyby` only
+
+## Migration Notes
+
+### Updating Deprecated status="off"
+
+```isml
+<!-- Old (deprecated) -->
+<iscache status="off"/>
+
+<!-- New: Just omit element -->
+<!-- (no iscache element) -->
+
+<!-- Or: Use if attribute for conditional -->
+<iscache type="relative" hour="1" if="${!pdict.disableCache}"/>
+```
+
+### SiteGenesis to SFRA
+
+```isml
+<!-- SiteGenesis -->
+<iscache type="relative" hour="1" varyby="price_promotion"/>
+
+<!-- SFRA (same syntax) -->
+<iscache type="relative" hour="1" varyby="price_promotion"/>
+```
+
+Syntax remains the same; review all cached pages to ensure no session data is cached.