sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/isml/iscache.md

@@ -1,802 +0,0 @@
-# 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.