sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/isml/iscomponent.md

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