sfcc-dev-mcp 1.0.15 → 1.0.19

package/dist/docs/isml/iscomponent.md

@@ -0,0 +1,797 @@
+# ISML iscomponent Element
+
+## Overview
+
+The `<iscomponent>` element includes the output of a pipeline or controller in the current page, functioning as a remote include with explicit pipeline-based syntax. It enables embedding reusable functionality encapsulated in pipelines/controllers while allowing independent caching policies. This element makes the purpose of remote includes obvious by directly associating them with specific pipelines or controllers.
+
+**Key Difference from `<isinclude>`:** `<iscomponent>` performs a remote server request to execute a pipeline/controller, while `<isinclude>` (without `url` attribute) performs a local template include.
+
+## Syntax
+
+```isml
+<iscomponent
+  pipeline   = pipeline_name        // required
+  locale     = locale_name          // optional
+  parameterN = valueN               // zero or more custom parameters
+/>
+```
+
+## Required Attributes
+
+### pipeline
+
+**Type:** String or Expression  
+**Required:** Yes
+
+Specifies the name of the pipeline or controller to execute. Uses the full pipeline syntax: `Pipeline-Node` or `Controller-Endpoint`.
+
+**Important:** SEO URLs cannot be used. You must use the full pipeline/controller syntax.
+
+```isml
+<!-- String literal -->
+<iscomponent pipeline="Product-Show" />
+
+<!-- Expression -->
+<iscomponent pipeline="${pdict.componentPipeline}" />
+
+<!-- SFRA Controller syntax -->
+<iscomponent pipeline="Product-ShowQuickView" />
+
+<!-- Legacy pipeline syntax -->
+<iscomponent pipeline="Product-Show" />
+```
+
+**Examples:**
+- `"Product-Show"` - Product controller Show endpoint
+- `"Search-Show"` - Search controller Show endpoint
+- `"Page-Include"` - Page controller Include endpoint
+- `"Account-Header"` - Account controller Header endpoint
+
+## Optional Attributes
+
+### locale
+
+**Type:** String or Expression  
+**Optional:** Yes
+
+Specifies an optional locale for the pipeline call. Overrides the current request locale for the component execution.
+
+```isml
+<!-- String literal locale -->
+<iscomponent pipeline="Product-Show" locale="en_US" productid="123" />
+
+<!-- Expression locale -->
+<iscomponent pipeline="Product-Show" locale="${pdict.preferredLocale}" productid="123" />
+
+<!-- Default locale (from request) -->
+<iscomponent pipeline="Product-Show" productid="123" />
+```
+
+**Use Cases:**
+- Multi-language components
+- Locale-specific content rendering
+- International site components
+
+### Custom Parameters (parameterN = valueN)
+
+**Type:** Any (passed as query parameters)  
+**Optional:** Yes (zero or more)
+
+Define any number of additional parameters that are passed to the pipeline/controller. These parameters are accessible in the controller via `request.httpParameterMap` or as query string parameters.
+
+```isml
+<!-- Single parameter -->
+<iscomponent pipeline="Product-Show" productid="12345" />
+
+<!-- Multiple parameters -->
+<iscomponent 
+  pipeline="Product-Show" 
+  productid="12345" 
+  name="Wide-screen television"
+  view="quickview"
+/>
+
+<!-- Expression parameters -->
+<iscomponent 
+  pipeline="Product-Show" 
+  productid="${product.ID}" 
+  source="recommendation"
+/>
+```
+
+**In the controller, access parameters:**
+```javascript
+// Controller: Product-Show
+server.get('Show', function (req, res, next) {
+    var productid = request.httpParameterMap.productid.stringValue;
+    var name = request.httpParameterMap.name.stringValue;
+    var view = request.httpParameterMap.view.stringValue;
+    
+    // Use parameters to customize output
+    res.render('product/productQuickView', {
+        productID: productid,
+        productName: name,
+        viewType: view
+    });
+    
+    next();
+});
+```
+
+## Purpose
+
+The `<iscomponent>` element serves several key purposes:
+
+1. **Remote Pipeline Execution:** Execute a pipeline/controller and include its output
+2. **Reusable Components:** Embed encapsulated functionality across multiple pages
+3. **Independent Caching:** Allow component to have different caching policy than parent page
+4. **Clear Intent:** Make the purpose of remote includes obvious through pipeline association
+5. **Modular Architecture:** Separate concerns by isolating component logic in dedicated controllers
+6. **Dynamic Content:** Include personalized or session-specific content in cached pages
+
+### Technical Behavior
+
+**Remote Include:**
+- Performs a **server-side HTTP request** to the specified pipeline/controller
+- Executes the pipeline/controller independently
+- Returns rendered HTML that is inserted into the parent page
+- Component has its own execution context and caching policy
+
+**Caching Independence:**
+- Parent page can be cached while component remains dynamic
+- Component can be cached while parent page is dynamic
+- Each has separate `<iscache>` directives
+
+## Common Use Cases
+
+### Product Quick View Modal
+
+```isml
+<!-- search/productGrid.isml (parent page - cached) -->
+<iscache type="relative" hour="1"/>
+
+<div class="product-grid">
+    <isloop items="${pdict.products}" var="product">
+        <div class="product-tile">
+            <h3>${product.name}</h3>
+            <button class="quick-view" data-pid="${product.id}">Quick View</button>
+        </div>
+    </isloop>
+</div>
+
+<!-- Modal container where quick view is loaded -->
+<div id="quickview-modal" class="modal">
+    <!-- Component loaded here via AJAX when quick view clicked -->
+</div>
+```
+
+```isml
+<!-- product/quickView.isml (component - not cached) -->
+<!-- No iscache - always fresh data -->
+
+<iscomponent 
+  pipeline="Product-ShowQuickView" 
+  productid="${pdict.pid}" 
+  source="quickview"
+/>
+```
+
+```javascript
+// Controller: Product-ShowQuickView
+server.get('ShowQuickView', function (req, res, next) {
+    var ProductFactory = require('*/cartridge/scripts/factories/product');
+    var productID = request.httpParameterMap.productid.stringValue;
+    var product = ProductFactory.get(productID);
+    
+    res.render('product/quickViewContent', {
+        product: product
+    });
+    
+    next();
+});
+```
+
+### Mini Cart (Dynamic in Cached Page)
+
+```isml
+<!-- homepage.isml (cached) -->
+<iscache type="daily"/>
+
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Welcome</title>
+</head>
+<body>
+    <header>
+        <div class="logo">Company Logo</div>
+        
+        <!-- Mini cart component (dynamic, not cached) -->
+        <iscomponent pipeline="Cart-MiniCart" />
+    </header>
+    
+    <!-- Cached homepage content -->
+    <div class="homepage-content">
+        <!-- Static/cached content -->
+    </div>
+</body>
+</html>
+```
+
+```isml
+<!-- cart/miniCart.isml (component) -->
+<!-- No cache - always shows current basket -->
+
+<div class="mini-cart">
+    <span class="item-count">${pdict.Basket.productQuantityTotal}</span>
+    <span class="total">${pdict.Basket.totalGrossPrice}</span>
+    
+    <div class="mini-cart-dropdown">
+        <isloop items="${pdict.Basket.productLineItems}" var="item">
+            <div class="mini-cart-item">
+                <span>${item.productName}</span>
+                <span>${item.price}</span>
+            </div>
+        </isloop>
+    </div>
+</div>
+```
+
+### User Account Greeting
+
+```isml
+<!-- Cached page with dynamic greeting -->
+<iscache type="relative" hour="2"/>
+
+<div class="page-header">
+    <!-- Dynamic user greeting (not cached) -->
+    <iscomponent pipeline="Account-Header" />
+    
+    <!-- Cached page content -->
+    <div class="content">
+        <!-- Static content -->
+    </div>
+</div>
+```
+
+```isml
+<!-- account/header.isml -->
+<div class="user-greeting">
+    <isif condition="${customer.authenticated}">
+        <span>Welcome back, ${customer.profile.firstName}!</span>
+        <a href="${URLUtils.url('Account-Show')}">My Account</a>
+    <iselse>
+        <a href="${URLUtils.url('Login-Show')}">Sign In</a>
+    </isif>
+</div>
+```
+
+### Product Recommendations (Personalized)
+
+```isml
+<!-- product/productDetails.isml (cached) -->
+<iscache type="relative" hour="1"/>
+
+<div class="product-detail">
+    <h1>${pdict.Product.name}</h1>
+    <p>${pdict.Product.longDescription}</p>
+    
+    <!-- Static product details (cached) -->
+</div>
+
+<!-- Einstein recommendations (personalized, not cached) -->
+<div class="recommendations">
+    <h2>Recommended for You</h2>
+    <iscomponent 
+      pipeline="Einstein-Recommendations" 
+      productid="${pdict.Product.ID}"
+      type="pdp-recs"
+    />
+</div>
+```
+
+### Locale-Specific Content
+
+```isml
+<!-- Multi-language footer component -->
+<div class="page-footer">
+    <iscomponent 
+      pipeline="Page-Footer" 
+      locale="en_US"
+    />
+</div>
+
+<!-- Or dynamic locale -->
+<div class="page-footer">
+    <iscomponent 
+      pipeline="Page-Footer" 
+      locale="${pdict.currentLocale}"
+    />
+</div>
+```
+
+### Store Locator Widget
+
+```isml
+<!-- Homepage with store locator -->
+<iscache type="daily"/>
+
+<div class="homepage">
+    <h1>Welcome to Our Store</h1>
+    
+    <!-- Store locator component (may have different cache) -->
+    <iscomponent 
+      pipeline="Stores-NearestStores" 
+      lat="${pdict.userLat}"
+      lng="${pdict.userLng}"
+      limit="5"
+    />
+</div>
+```
+
+### Recently Viewed Products
+
+```isml
+<!-- Cached product page with dynamic recently viewed -->
+<iscache type="relative" hour="1" varyby="price_promotion"/>
+
+<div class="product-page">
+    <!-- Product details (cached) -->
+    
+    <div class="recently-viewed">
+        <h3>Recently Viewed</h3>
+        <!-- Dynamic, session-specific content -->
+        <iscomponent pipeline="Product-RecentlyViewed" />
+    </div>
+</div>
+```
+
+### Promotional Banner (Time-Sensitive)
+
+```isml
+<!-- Cached page with dynamic promotional banner -->
+<iscache type="relative" hour="4"/>
+
+<div class="homepage">
+    <!-- Dynamic promotional banner (updates every 15 minutes) -->
+    <iscomponent pipeline="Content-PromotionalBanner" />
+    
+    <!-- Cached homepage content (updates every 4 hours) -->
+    <div class="featured-products">
+        <!-- Products -->
+    </div>
+</div>
+```
+
+Component can have shorter cache:
+```isml
+<!-- content/promotionalBanner.isml -->
+<iscache type="relative" minute="15"/>
+
+<div class="promo-banner">
+    <img src="${pdict.banner.imageURL}" alt="${pdict.banner.alt}" />
+    <h2>${pdict.banner.headline}</h2>
+</div>
+```
+
+## Best Practices
+
+1. **Use for Dynamic Content in Cached Pages:**
+   ```isml
+   <!-- Cached page -->
+   <iscache type="relative" hour="2"/>
+   
+   <!-- Dynamic component -->
+   <iscomponent pipeline="Cart-MiniCart" />
+   ```
+
+2. **Pass All Required Parameters:**
+   ```isml
+   <!-- Good: All parameters provided -->
+   <iscomponent 
+     pipeline="Product-Show" 
+     productid="${product.ID}"
+     view="quickview"
+   />
+   
+   <!-- Bad: Missing required parameter -->
+   <iscomponent pipeline="Product-Show" />
+   ```
+
+3. **Use Descriptive Parameter Names:**
+   ```isml
+   <!-- Good: Clear parameter names -->
+   <iscomponent 
+     pipeline="Search-Show" 
+     query="${searchTerm}"
+     category="${categoryID}"
+     resultsPerPage="12"
+   />
+   ```
+
+4. **Handle Component Errors Gracefully:**
+   ```isml
+   <!-- In parent template -->
+   <iscomponent pipeline="Recommendations-Show" productid="${pdict.Product.ID}" />
+   
+   <!-- In component controller -->
+   // Handle missing product gracefully
+   if (!product) {
+       res.render('components/empty');
+       return next();
+   }
+   ```
+
+5. **Consider Performance Impact:**
+   ```isml
+   <iscomment>
+       Each iscomponent is a separate server request
+       Use sparingly to avoid performance degradation
+   </iscomment>
+   
+   <!-- Good: One component for related functionality -->
+   <iscomponent pipeline="Product-Recommendations" />
+   
+   <!-- Bad: Multiple separate components for same feature -->
+   <iscomponent pipeline="Product-Recommendation1" />
+   <iscomponent pipeline="Product-Recommendation2" />
+   <iscomponent pipeline="Product-Recommendation3" />
+   ```
+
+6. **Use Full Pipeline Syntax:**
+   ```isml
+   <!-- Good: Full pipeline syntax -->
+   <iscomponent pipeline="Product-Show" />
+   
+   <!-- Bad: SEO URL (not supported) -->
+   <iscomponent pipeline="/product/wide-screen-tv-12345.html" />
+   ```
+
+7. **Document Component Dependencies:**
+   ```isml
+   <iscomment>
+       User Greeting Component
+       Pipeline: Account-Header
+       Required Parameters: None
+       Caching: Not cached (session-specific)
+       Purpose: Display user greeting or login link
+   </iscomment>
+   
+   <iscomponent pipeline="Account-Header" />
+   ```
+
+8. **Test Component Independently:**
+   ```javascript
+   // Component should work standalone
+   server.get('MiniCart', function (req, res, next) {
+       var BasketMgr = require('dw/order/BasketMgr');
+       var basket = BasketMgr.getCurrentBasket();
+       
+       // Render even if no basket
+       res.render('components/miniCart', {
+           Basket: basket || null
+       });
+       
+       next();
+   });
+   ```
+
+## Caching Strategies
+
+### Parent Cached, Component Dynamic
+
+```isml
+<!-- Parent: category.isml -->
+<iscache type="relative" hour="2"/>
+
+<div class="category-page">
+    <!-- Cached category content -->
+    
+    <!-- Dynamic user-specific content -->
+    <iscomponent pipeline="User-Recommendations" />
+</div>
+```
+
+**Use Case:** Category page content rarely changes, but recommendations are personalized.
+
+### Parent Dynamic, Component Cached
+
+```isml
+<!-- Parent: account.isml -->
+<!-- No cache (user-specific) -->
+
+<div class="account-page">
+    <h1>My Account</h1>
+    <p>Welcome, ${customer.profile.firstName}!</p>
+    
+    <!-- Cached help content (same for all users) -->
+    <iscomponent pipeline="Content-HelpSection" />
+</div>
+```
+
+**Use Case:** Account page is personalized, but help content is static.
+
+### Both Cached (Different Durations)
+
+```isml
+<!-- Parent: homepage.isml -->
+<iscache type="daily"/>
+
+<div class="homepage">
+    <!-- Daily cache -->
+    
+    <!-- Component with shorter cache -->
+    <iscomponent pipeline="Content-DailyDeal" />
+</div>
+```
+
+Component:
+```isml
+<!-- content/dailyDeal.isml -->
+<iscache type="relative" hour="1"/>
+
+<div class="daily-deal">
+    <!-- Updates every hour -->
+</div>
+```
+
+**Use Case:** Homepage updates daily, but daily deal changes hourly.
+
+### Both Dynamic (Different Logic)
+
+```isml
+<!-- Parent: checkout.isml -->
+<!-- No cache (order-specific) -->
+
+<div class="checkout-page">
+    <!-- Order details -->
+    
+    <!-- Dynamic shipping options component -->
+    <iscomponent 
+      pipeline="Checkout-ShippingOptions" 
+      addressid="${pdict.shippingAddress.ID}"
+    />
+</div>
+```
+
+**Use Case:** Both need to be dynamic but have separate concerns.
+
+## Comparison with Other Include Methods
+
+| Feature | `<iscomponent>` | `<isinclude template>` | `<isinclude url>` |
+|---------|----------------|----------------------|------------------|
+| **Type** | Remote (server request) | Local (file include) | Remote (HTTP request) |
+| **Execution** | Pipeline/Controller | Template only | Any URL |
+| **Caching** | Independent | Inherits parent | Independent |
+| **Parameters** | Custom attributes | pdict only | URL parameters |
+| **Performance** | Slower (HTTP) | Fast (file) | Slower (HTTP) |
+| **Use Case** | Reusable components | Template fragments | External content |
+| **Syntax** | Pipeline-based | File path | Full URL |
+
+```isml
+<!-- iscomponent: Remote pipeline execution -->
+<iscomponent pipeline="Product-Show" productid="123" />
+
+<!-- isinclude template: Local template include -->
+<isinclude template="components/productTile" />
+
+<!-- isinclude url: Remote URL include -->
+<isinclude url="${URLUtils.url('Product-Show', 'pid', '123')}" />
+```
+
+## Parameter Handling
+
+### Accessing Parameters in Controller
+
+```javascript
+// SFRA Controller
+server.get('ShowQuickView', function (req, res, next) {
+    // Method 1: httpParameterMap
+    var productID = request.httpParameterMap.productid.stringValue;
+    var source = request.httpParameterMap.source.stringValue;
+    
+    // Method 2: req.querystring (SFRA)
+    var productID = req.querystring.productid;
+    var source = req.querystring.source;
+    
+    res.render('template', {
+        productID: productID,
+        source: source
+    });
+    
+    next();
+});
+```
+
+### Parameter Types
+
+```isml
+<!-- String parameters -->
+<iscomponent pipeline="Product-Show" productid="12345" />
+
+<!-- Numeric parameters -->
+<iscomponent pipeline="Search-Show" start="0" count="12" />
+
+<!-- Boolean parameters -->
+<iscomponent pipeline="Content-Show" showprices="true" />
+
+<!-- Expression parameters -->
+<iscomponent 
+  pipeline="Product-Show" 
+  productid="${product.ID}"
+  quantity="${selectedQuantity}"
+/>
+```
+
+## Error Handling
+
+### Component Controller Error Handling
+
+```javascript
+server.get('Recommendations', function (req, res, next) {
+    try {
+        var productID = request.httpParameterMap.productid.stringValue;
+        
+        if (!productID) {
+            // Render empty component
+            res.render('components/empty');
+            return next();
+        }
+        
+        var recommendations = getRecommendations(productID);
+        
+        res.render('components/recommendations', {
+            recommendations: recommendations
+        });
+    } catch (e) {
+        // Log error and render fallback
+        Logger.error('Recommendations component failed: ' + e.message);
+        res.render('components/empty');
+    }
+    
+    next();
+});
+```
+
+### Parent Template Error Handling
+
+```isml
+<!-- Component may fail gracefully -->
+<div class="recommendations">
+    <iscomponent 
+      pipeline="Einstein-Recommendations" 
+      productid="${pdict.Product.ID}"
+    />
+    <!-- If component fails, renders empty or fallback -->
+</div>
+
+<!-- Page continues normally -->
+<div class="product-details">
+    <!-- Product information -->
+</div>
+```
+
+## Performance Considerations
+
+### Impact
+
+- **Server Request:** Each `<iscomponent>` performs a separate server-side HTTP request
+- **Latency:** Adds latency to page rendering (sequential execution)
+- **Resource Usage:** Multiple components increase server load
+
+### Optimization Strategies
+
+1. **Minimize Component Count:**
+   ```isml
+   <!-- Better: One component -->
+   <iscomponent pipeline="Product-AllRecommendations" />
+   
+   <!-- Avoid: Multiple components -->
+   <iscomponent pipeline="Product-Recommendation1" />
+   <iscomponent pipeline="Product-Recommendation2" />
+   <iscomponent pipeline="Product-Recommendation3" />
+   ```
+
+2. **Cache Components When Possible:**
+   ```isml
+   <!-- Component template with caching -->
+   <iscache type="relative" minute="30"/>
+   
+   <div class="component-content">
+       <!-- Cached component output -->
+   </div>
+   ```
+
+3. **Use Async Loading for Non-Critical Components:**
+   ```isml
+   <!-- Critical content -->
+   <div class="main-content">
+       ${pdict.Product.name}
+   </div>
+   
+   <!-- Non-critical component (could be AJAX-loaded) -->
+   <div id="recommendations-container" data-pid="${pdict.Product.ID}">
+       <!-- Load via JavaScript after page load -->
+   </div>
+   ```
+
+4. **Combine Related Functionality:**
+   ```javascript
+   // Good: One controller handles related data
+   server.get('ProductExtras', function (req, res, next) {
+       var recommendations = getRecommendations(productID);
+       var reviews = getReviews(productID);
+       var relatedProducts = getRelatedProducts(productID);
+       
+       res.render('components/productExtras', {
+           recommendations: recommendations,
+           reviews: reviews,
+           relatedProducts: relatedProducts
+       });
+       
+       next();
+   });
+   ```
+
+## SEO and URL Considerations
+
+⚠️ **Important:** SEO URLs cannot be used with `<iscomponent>`.
+
+```isml
+<!-- Good: Full pipeline syntax -->
+<iscomponent pipeline="Product-Show" productid="12345" />
+
+<!-- Bad: SEO URL (NOT SUPPORTED) -->
+<iscomponent pipeline="/product/wide-screen-tv-12345.html" />
+
+<!-- Bad: Pretty URL (NOT SUPPORTED) -->
+<iscomponent pipeline="/s/Site/Product-Show?pid=12345" />
+```
+
+**Always use:** `Controller-Endpoint` format.
+
+## Related Elements
+
+- `<isinclude template>` - Local template include (faster, shares cache)
+- `<isinclude url>` - Remote URL include (similar to iscomponent)
+- `<iscache>` - Control caching policy for component
+- `<isdecorate>` - Template decoration (use with components)
+
+## Notes
+
+- Performs remote server-side HTTP request to execute pipeline/controller
+- Each component has independent caching policy
+- Parameters passed as query string parameters
+- Full pipeline syntax required (SEO URLs not supported)
+- Slower than local includes due to HTTP request overhead
+- Ideal for embedding reusable, encapsulated functionality
+- Component can be personalized while parent page is cached
+- Use sparingly to avoid performance degradation
+- Component failures should be handled gracefully
+- Makes remote include purpose obvious through pipeline association
+
+## Migration Notes
+
+### Legacy Pipelines to SFRA Controllers
+
+```isml
+<!-- Legacy Pipeline Syntax -->
+<iscomponent pipeline="Product-Show" productid="12345" />
+
+<!-- SFRA Controller Syntax (same format) -->
+<iscomponent pipeline="Product-Show" productid="12345" />
+```
+
+The syntax remains the same; only the underlying implementation changes from pipelines to SFRA controllers.
+
+### Converting Remote Includes to iscomponent
+
+```isml
+<!-- Before: Remote include with URL -->
+<isinclude url="${URLUtils.url('Product-Show', 'pid', '12345')}" />
+
+<!-- After: Component (clearer intent) -->
+<iscomponent pipeline="Product-Show" productid="12345" />
+```
+
+Benefits: Clearer purpose, easier to understand, more maintainable.