sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/isml/isscript.md

@@ -1,859 +0,0 @@
-# ISML isscript Element
-
-## Overview
-
-The `<isscript>` element enables server-side JavaScript execution within ISML templates. It provides a way to perform calculations, manipulate data, call API methods, and set variables using the full power of JavaScript and the Salesforce B2C Commerce Script API (dw.* namespace).
-
-**Key Features:** Server-side JavaScript execution, access to B2C Commerce APIs, variable manipulation, shared execution context across multiple script blocks, integration with inline expressions using `${}` syntax.
-
-**Important:** Scripts execute on the server during template rendering, not in the browser.
-
-## Syntax
-
-```isml
-<isscript>
-  // JavaScript code here
-</isscript>
-```
-
-## Attributes
-
-**None** - This tag has no attributes. JavaScript code is placed between the opening and closing tags.
-
-## Purpose
-
-The `<isscript>` element serves to:
-
-1. **Server-Side Logic:** Execute JavaScript business logic during template rendering
-2. **Data Manipulation:** Transform, calculate, or process data before display
-3. **API Access:** Call B2C Commerce Script API methods (dw.* namespace)
-4. **Variable Assignment:** Create and set variables for use in templates
-5. **Complex Operations:** Perform operations too complex for inline expressions
-6. **Code Organization:** Group related logic in dedicated script blocks
-
-## Top-Level Variables
-
-The following variables are automatically available in all `<isscript>` blocks:
-
-| Variable | Type | Description | Scope |
-|----------|------|-------------|-------|
-| `session` | `dw.system.Session` | Current internal B2C Commerce session | Session-wide |
-| `request` | `dw.system.Request` | Current internal B2C Commerce request | Request-wide |
-| `pdict` | `dw.system.PipelineDictionary` | Pipeline Dictionary (request parameters and data) | Request-wide |
-| `out` | `dw.io.PrintWriter` | PrintWriter for direct HTML output | Page-wide |
-
-**Example:**
-```isml
-<isscript>
-    // Access session
-    var customerId = session.customer.ID;
-    
-    // Access request
-    var httpMethod = request.httpMethod;
-    
-    // Access pipeline dictionary
-    var product = pdict.Product;
-    
-    // Write directly to output (uncommon)
-    out.print("<p>Hello World</p>");
-</isscript>
-```
-
-## Variable Scopes
-
-Variables created in `<isscript>` blocks have different scopes based on how they're declared:
-
-### Page Scope Variables
-
-**Definition:** Variables set using `var`, `let`, or `const` in scriptlets, or well-known variables set by the template at runtime.
-
-**Availability:** Available throughout template execution context and can be referenced from multiple scriptlets or expressions in the template or its local includes.
-
-**Persistence:** Lasts for the duration of the current page/template execution.
-
-```isml
-<isscript>
-    var userName = pdict.customer.firstName;  // Page scope
-    var orderTotal = pdict.basket.totalGrossPrice.value;  // Page scope
-</isscript>
-
-<!-- Variables available in expressions -->
-<h1>Welcome, ${userName}</h1>
-<p>Total: ${orderTotal}</p>
-
-<!-- Variables available in other script blocks -->
-<isscript>
-    var greeting = "Hello, " + userName;  // userName from previous block
-</isscript>
-```
-
-### Tag Scope Variables
-
-**Definition:** Variables defined within certain ISML tags (e.g., loop status variables).
-
-**Availability:** Only available within the context of that specific tag.
-
-**Example:**
-```isml
-<isloop items="${pdict.products}" var="product" status="loopStatus">
-    <!-- loopStatus is tag-scoped, only available inside this loop -->
-    <isif condition="${loopStatus.first}">
-        <p>First product!</p>
-    </isif>
-</isloop>
-<!-- loopStatus NOT available here -->
-```
-
-## Shared Execution Context
-
-**Important:** Multiple `<isscript>` blocks in the same template share the same execution context. Variables declared in one block are available in subsequent blocks.
-
-```isml
-<!-- First script block -->
-<isscript>
-    var user = pdict.User;
-    var firstName = user.firstName;
-</isscript>
-
-<!-- Some HTML content -->
-<div class="header">
-    <h1>Welcome</h1>
-</div>
-
-<!-- Second script block - can access variables from first block -->
-<isscript>
-    var fullName = firstName + " " + user.lastName;  // firstName and user available
-    var welcomeMessage = "Hello, " + fullName;
-</isscript>
-
-<!-- Use variables in expressions -->
-<p><isprint value="${welcomeMessage}"/></p>
-```
-
-## Common Use Cases
-
-### Data Transformation and Calculation
-
-```isml
-<isscript>
-    var product = pdict.Product;
-    
-    // Calculate discount percentage
-    var listPrice = product.price.list.value;
-    var salesPrice = product.price.sales.value;
-    var discount = listPrice - salesPrice;
-    var discountPercent = (discount / listPrice) * 100;
-    
-    // Format for display
-    var discountDisplay = Math.round(discountPercent) + "% OFF";
-</isscript>
-
-<div class="product-price">
-    <span class="original">${listPrice}</span>
-    <span class="sale">${salesPrice}</span>
-    <span class="discount">${discountDisplay}</span>
-</div>
-```
-
-### API Method Calls
-
-```isml
-<isscript>
-    var ProductMgr = require('dw/catalog/ProductMgr');
-    var URLUtils = require('dw/web/URLUtils');
-    var StringUtils = require('dw/util/StringUtils');
-    
-    // Get product by ID
-    var productID = request.httpParameterMap.pid.stringValue;
-    var product = ProductMgr.getProduct(productID);
-    
-    // Generate URLs
-    var productURL = URLUtils.url('Product-Show', 'pid', productID);
-    
-    // String manipulation
-    var productName = StringUtils.trim(product.name);
-</isscript>
-```
-
-### Complex Conditional Logic
-
-```isml
-<isscript>
-    var customer = session.customer;
-    var basket = pdict.basket;
-    
-    // Determine eligibility for free shipping
-    var freeShippingThreshold = 50;
-    var basketTotal = basket ? basket.totalGrossPrice.value : 0;
-    var isFreeShipping = basketTotal >= freeShippingThreshold;
-    var amountToFreeShipping = isFreeShipping ? 0 : freeShippingThreshold - basketTotal;
-    
-    // Determine customer tier
-    var customerTier = "bronze";
-    if (customer.authenticated) {
-        var orderHistory = customer.orderHistory;
-        var totalSpent = 0;
-        var orders = orderHistory.getOrders();
-        while (orders.hasNext()) {
-            var order = orders.next();
-            totalSpent += order.totalGrossPrice.value;
-        }
-        
-        if (totalSpent > 1000) {
-            customerTier = "gold";
-        } else if (totalSpent > 500) {
-            customerTier = "silver";
-        }
-    }
-</isscript>
-
-<div class="shipping-message">
-    <isif condition="${isFreeShipping}">
-        <p>You qualify for FREE shipping!</p>
-    <iselse>
-        <p>Add <isprint value="${amountToFreeShipping}" style="MONEY_LONG"/> for FREE shipping</p>
-    </isif>
-</div>
-
-<div class="customer-tier ${customerTier}">
-    <p>Your tier: ${customerTier.toUpperCase()}</p>
-</div>
-```
-
-### Array and Collection Processing
-
-```isml
-<isscript>
-    var products = pdict.products;
-    
-    // Filter products on sale
-    var saleProducts = [];
-    for (var i = 0; i < products.length; i++) {
-        var product = products[i];
-        if (product.price.sales.value < product.price.list.value) {
-            saleProducts.push(product);
-        }
-    }
-    
-    // Sort by price (low to high)
-    saleProducts.sort(function(a, b) {
-        return a.price.sales.value - b.price.sales.value;
-    });
-    
-    // Get top 5 cheapest sale items
-    var topDeals = saleProducts.slice(0, 5);
-</isscript>
-
-<div class="top-deals">
-    <h2>Top Deals</h2>
-    <isloop items="${topDeals}" var="deal">
-        <div class="deal-item">
-            <h3>${deal.name}</h3>
-            <p><isprint value="${deal.price.sales}" style="MONEY_LONG"/></p>
-        </div>
-    </isloop>
-</div>
-```
-
-### Date and Time Manipulation
-
-```isml
-<isscript>
-    var Calendar = require('dw/util/Calendar');
-    var StringUtils = require('dw/util/StringUtils');
-    
-    var now = new Calendar();
-    var currentDate = now.time;
-    
-    // Calculate shipping estimate (3 business days)
-    var shippingEstimate = new Calendar(now);
-    shippingEstimate.add(Calendar.DAY_OF_MONTH, 3);
-    
-    // Format dates
-    var orderDate = StringUtils.formatCalendar(now, "MMMM d, yyyy");
-    var deliveryDate = StringUtils.formatCalendar(shippingEstimate, "MMMM d, yyyy");
-</isscript>
-
-<div class="order-info">
-    <p>Order Date: ${orderDate}</p>
-    <p>Estimated Delivery: ${deliveryDate}</p>
-</div>
-```
-
-### Session and Cookie Management
-
-```isml
-<isscript>
-    var Cookie = require('dw/web/Cookie');
-    
-    // Read cookie
-    var cookies = request.httpCookies;
-    var viewedProducts = cookies['recentlyViewed'];
-    
-    // Set session custom property
-    if (!session.custom.pageViews) {
-        session.custom.pageViews = 0;
-    }
-    session.custom.pageViews++;
-    
-    var pageViewCount = session.custom.pageViews;
-    var isFirstVisit = pageViewCount === 1;
-</isscript>
-
-<isif condition="${isFirstVisit}">
-    <div class="welcome-modal">
-        <h2>Welcome to our store!</h2>
-        <p>First time here? Get 10% off your first order.</p>
-    </div>
-</isif>
-```
-
-### Form Validation and Processing
-
-```isml
-<isscript>
-    var form = pdict.CurrentForms.registration;
-    var errors = [];
-    
-    // Validate email
-    var email = form.email.value;
-    if (!email || email.indexOf('@') === -1) {
-        errors.push({
-            field: 'email',
-            message: 'Please enter a valid email address'
-        });
-    }
-    
-    // Validate password
-    var password = form.password.value;
-    var confirmPassword = form.confirmPassword.value;
-    if (password !== confirmPassword) {
-        errors.push({
-            field: 'password',
-            message: 'Passwords do not match'
-        });
-    }
-    
-    var hasErrors = errors.length > 0;
-</isscript>
-
-<isif condition="${hasErrors}">
-    <div class="error-messages">
-        <isloop items="${errors}" var="error">
-            <p class="error">${error.message}</p>
-        </isloop>
-    </div>
-</isif>
-```
-
-### Custom Object Access
-
-```isml
-<isscript>
-    var CustomObjectMgr = require('dw/object/CustomObjectMgr');
-    
-    // Retrieve custom object
-    var storeConfig = CustomObjectMgr.getCustomObject('StoreConfig', 'main');
-    
-    if (storeConfig) {
-        var storeName = storeConfig.custom.storeName;
-        var storeHours = storeConfig.custom.hours;
-        var storePhone = storeConfig.custom.phone;
-    } else {
-        var storeName = "Our Store";
-        var storeHours = "9 AM - 5 PM";
-        var storePhone = "1-800-555-0123";
-    }
-</isscript>
-
-<div class="store-info">
-    <h3>${storeName}</h3>
-    <p>Hours: ${storeHours}</p>
-    <p>Phone: ${storePhone}</p>
-</div>
-```
-
-### SFRA-Style Module Imports
-
-```isml
-<isscript>
-    // Import modules
-    var ProductFactory = require('*/cartridge/scripts/factories/product');
-    var collections = require('*/cartridge/scripts/util/collections');
-    var URLUtils = require('dw/web/URLUtils');
-    
-    // Use imported modules
-    var productDetails = ProductFactory.get(pdict.product);
-    
-    var productImages = collections.map(productDetails.images.large, function(image) {
-        return {
-            url: image.url,
-            alt: image.alt,
-            title: image.title
-        };
-    });
-    
-    var addToCartUrl = URLUtils.url('Cart-AddProduct');
-</isscript>
-```
-
-### JSON Data Preparation
-
-```isml
-<isscript>
-    var product = pdict.Product;
-    
-    // Prepare JSON data for client-side JavaScript
-    var productData = {
-        id: product.ID,
-        name: product.name,
-        price: product.price.sales.value,
-        currency: product.price.sales.currencyCode,
-        available: product.available,
-        inStock: product.availabilityModel.inStock,
-        images: []
-    };
-    
-    // Build images array
-    var images = product.getImages('large');
-    for (var i = 0; i < images.length; i++) {
-        productData.images.push({
-            url: images[i].getURL().toString(),
-            alt: images[i].getAlt()
-        });
-    }
-    
-    var productJSON = JSON.stringify(productData);
-</isscript>
-
-<script>
-    window.productData = ${productJSON};
-</script>
-```
-
-## Best Practices
-
-### 1. Keep Scripts Focused and Small
-
-Break large scripts into smaller, focused blocks:
-
-```isml
-<!-- Good: Small, focused script blocks -->
-<isscript>
-    var product = pdict.Product;
-    var price = product.price.sales.value;
-</isscript>
-
-<!-- Display product info -->
-<div class="product">${product.name}</div>
-
-<isscript>
-    var discount = calculateDiscount(price);
-</isscript>
-
-<!-- Avoid: One large script block with everything -->
-<isscript>
-    // 100 lines of mixed logic
-</isscript>
-```
-
-### 2. Use require() for API Access
-
-Always use `require()` to import B2C Commerce API classes:
-
-```isml
-<!-- Good: Explicit require statements -->
-<isscript>
-    var ProductMgr = require('dw/catalog/ProductMgr');
-    var URLUtils = require('dw/web/URLUtils');
-    
-    var product = ProductMgr.getProduct(productID);
-</isscript>
-
-<!-- Avoid: Assuming classes are globally available -->
-<isscript>
-    var product = ProductMgr.getProduct(productID);  // May not work
-</isscript>
-```
-
-### 3. Minimize Business Logic in Templates
-
-Move complex business logic to controllers or scripts:
-
-```isml
-<!-- Good: Simple data access in template -->
-<isscript>
-    var productHelper = require('*/cartridge/scripts/helpers/productHelper');
-    var productData = productHelper.getProductData(pdict.Product);
-</isscript>
-
-<!-- Avoid: Complex business logic in template -->
-<isscript>
-    // 50 lines of complex pricing calculations
-    // Discount rules
-    // Inventory checks
-    // etc.
-</isscript>
-```
-
-### 4. Use Descriptive Variable Names
-
-Choose clear, meaningful variable names:
-
-```isml
-<!-- Good: Descriptive names -->
-<isscript>
-    var currentProduct = pdict.Product;
-    var discountPercentage = calculateDiscount(currentProduct);
-    var formattedPrice = formatCurrency(currentProduct.price);
-</isscript>
-
-<!-- Avoid: Unclear names -->
-<isscript>
-    var p = pdict.Product;
-    var d = calc(p);
-    var f = fmt(p.price);
-</isscript>
-```
-
-### 5. Handle Null and Undefined Safely
-
-Always check for null/undefined before accessing properties:
-
-```isml
-<isscript>
-    var product = pdict.Product;
-    var productName = product ? product.name : "Product Unavailable";
-    
-    var basket = pdict.basket;
-    var itemCount = basket && basket.productLineItems ? basket.productLineItems.size() : 0;
-    
-    // Or use optional chaining if available
-    var manufacturer = product?.manufacturer?.name || "Unknown";
-</isscript>
-```
-
-### 6. Avoid Direct HTML Output with out.print()
-
-Use ISML elements instead of `out.print()`:
-
-```isml
-<!-- Good: Use ISML elements -->
-<isscript>
-    var message = "Welcome, " + customer.firstName;
-</isscript>
-<p>${message}</p>
-
-<!-- Avoid: Direct HTML output -->
-<isscript>
-    out.print("<p>Welcome, " + customer.firstName + "</p>");
-</isscript>
-```
-
-### 7. Comment Complex Logic
-
-Add comments to explain non-obvious logic:
-
-```isml
-<isscript>
-    // Calculate loyalty discount based on customer tier and purchase history
-    var loyaltyDiscount = 0;
-    if (customer.authenticated) {
-        var tier = customer.custom.loyaltyTier;
-        var purchaseCount = customer.orderHistory.orderCount;
-        
-        // Gold tier: 15% discount, Silver: 10%, Bronze: 5%
-        if (tier === 'gold' && purchaseCount > 10) {
-            loyaltyDiscount = 0.15;
-        } else if (tier === 'silver' && purchaseCount > 5) {
-            loyaltyDiscount = 0.10;
-        } else {
-            loyaltyDiscount = 0.05;
-        }
-    }
-</isscript>
-```
-
-### 8. Use Modern JavaScript Features
-
-Leverage ES6+ features when appropriate:
-
-```isml
-<isscript>
-    // Use const/let instead of var when appropriate
-    const TAX_RATE = 0.08;
-    let totalWithTax = subtotal * (1 + TAX_RATE);
-    
-    // Use arrow functions
-    const activeProducts = products.filter(p => p.online && p.available);
-    
-    // Use template literals
-    const greeting = `Welcome, ${customer.firstName} ${customer.lastName}!`;
-    
-    // Use destructuring
-    const { firstName, lastName, email } = customer.profile;
-</isscript>
-```
-
-## Integration with Inline Expressions
-
-Variables created in `<isscript>` blocks are available in inline expressions `${}`:
-
-```isml
-<isscript>
-    var userName = pdict.customer.firstName + " " + pdict.customer.lastName;
-    var currentYear = new Date().getFullYear();
-    var copyrightText = "© " + currentYear + " Our Company";
-</isscript>
-
-<!-- Use variables in inline expressions -->
-<h1>Welcome, ${userName}</h1>
-<footer>
-    <p>${copyrightText}</p>
-</footer>
-
-<!-- Use in attributes -->
-<div class="user-${userName.toLowerCase().replace(' ', '-')}">
-    Content
-</div>
-
-<!-- Use in isprint -->
-<isprint value="${userName}" encoding="on"/>
-```
-
-## Script Expression Support
-
-Script expressions using `${}` syntax are supported in various contexts:
-
-### In HTML Content
-
-```isml
-<p>Hello, ${customer.firstName}!</p>
-<h2>${product.name}</h2>
-```
-
-### In Tag Attributes
-
-```isml
-<div class="${pdict.cssClass}">
-<img src="${product.imageURL}" alt="${product.name}">
-<a href="${URLUtils.url('Product-Show', 'pid', product.ID)}">
-```
-
-### In ISML Tag Attributes
-
-```isml
-<isif condition="${product.available}">
-<isprint value="${product.price}" style="MONEY_LONG"/>
-<isloop items="${pdict.products}" var="product">
-```
-
-## Performance Considerations
-
-### 1. Minimize Script Execution Time
-
-Keep scripts efficient to avoid slow page rendering:
-
-```isml
-<!-- Good: Efficient operations -->
-<isscript>
-    var productCount = products.length;  // Fast
-    var firstProduct = products[0];       // Fast
-</isscript>
-
-<!-- Avoid: Expensive operations in templates -->
-<isscript>
-    // Expensive database queries
-    // Complex calculations
-    // Large loops processing thousands of items
-</isscript>
-```
-
-### 2. Cache Expensive Calculations
-
-Store results of expensive calculations:
-
-```isml
-<isscript>
-    // Cache result in session for reuse
-    if (!session.custom.cachedData) {
-        session.custom.cachedData = expensiveCalculation();
-    }
-    var data = session.custom.cachedData;
-</isscript>
-```
-
-### 3. Avoid Nested Loops
-
-Minimize nested iterations:
-
-```isml
-<!-- Less efficient: Nested loops -->
-<isscript>
-    for (var i = 0; i < products.length; i++) {
-        for (var j = 0; j < categories.length; j++) {
-            // O(n²) complexity
-        }
-    }
-</isscript>
-
-<!-- Better: Pre-process data -->
-<isscript>
-    var categoryMap = {};
-    categories.forEach(function(cat) {
-        categoryMap[cat.ID] = cat;
-    });
-    
-    products.forEach(function(prod) {
-        var category = categoryMap[prod.categoryID];  // O(1) lookup
-    });
-</isscript>
-```
-
-## Security Considerations
-
-### 1. Sanitize User Input
-
-Never trust user input in scripts:
-
-```isml
-<isscript>
-    var searchQuery = request.httpParameterMap.q.stringValue;
-    
-    // Sanitize before use
-    var StringUtils = require('dw/util/StringUtils');
-    var safeQuery = StringUtils.trim(searchQuery || '');
-    
-    // Validate
-    if (safeQuery.length > 100) {
-        safeQuery = safeQuery.substring(0, 100);
-    }
-</isscript>
-```
-
-### 2. Avoid Exposing Sensitive Data
-
-Don't expose sensitive information to client-side:
-
-```isml
-<!-- Bad: Exposing sensitive data -->
-<isscript>
-    var customerData = {
-        email: customer.email,
-        password: customer.password,  // NEVER DO THIS
-        creditCard: customer.creditCard  // NEVER DO THIS
-    };
-</isscript>
-<script>
-    window.customer = ${JSON.stringify(customerData)};
-</script>
-
-<!-- Good: Only expose safe data -->
-<isscript>
-    var customerData = {
-        firstName: customer.firstName,
-        loyaltyPoints: customer.loyaltyPoints
-    };
-</isscript>
-```
-
-### 3. Use Proper Encoding
-
-Encode output to prevent XSS:
-
-```isml
-<isscript>
-    var userComment = request.httpParameterMap.comment.stringValue;
-</isscript>
-
-<!-- Good: Use encoding -->
-<p><isprint value="${userComment}" encoding="on"/></p>
-
-<!-- Bad: Direct output without encoding -->
-<p>${userComment}</p>  <!-- Potential XSS -->
-```
-
-## Common Errors and Troubleshooting
-
-### Script Syntax Errors
-
-**Symptom:** Template fails to render with JavaScript error.
-
-**Solution:** Check JavaScript syntax carefully:
-
-```isml
-<!-- Bad: Syntax error -->
-<isscript>
-    var product = pdict.Product
-    var price = product.price  // Missing semicolon
-</isscript>
-
-<!-- Good: Correct syntax -->
-<isscript>
-    var product = pdict.Product;
-    var price = product.price;
-</isscript>
-```
-
-### Variable Not Defined
-
-**Symptom:** ReferenceError - variable is not defined.
-
-**Solution:** Ensure variable is declared before use:
-
-```isml
-<!-- Bad: Using undeclared variable -->
-<isscript>
-    var fullName = firstName + " " + lastName;  // firstName not defined
-</isscript>
-
-<!-- Good: Declare variables -->
-<isscript>
-    var firstName = pdict.customer.firstName;
-    var lastName = pdict.customer.lastName;
-    var fullName = firstName + " " + lastName;
-</isscript>
-```
-
-### Null Pointer Errors
-
-**Symptom:** TypeError - cannot read property of null/undefined.
-
-**Solution:** Check for null/undefined:
-
-```isml
-<!-- Bad: No null check -->
-<isscript>
-    var productName = pdict.Product.name;  // Error if Product is null
-</isscript>
-
-<!-- Good: Null check -->
-<isscript>
-    var product = pdict.Product;
-    var productName = product ? product.name : "Unknown Product";
-</isscript>
-```
-
-## Related Elements
-
-- **`<isset>`** - Set variables (alternative to isscript for simple assignments)
-- **`<isprint>`** - Output script variables with formatting
-- **`<isif>`** - Use script variables in conditions
-- **`<isloop>`** - Iterate over collections created in scripts
-
-## Related APIs
-
-- **`dw.*` packages** - All B2C Commerce Script API classes
-- **`require()`** - Module import function
-- **`session`** - Session object
-- **`request`** - Request object  
-- **`pdict`** - Pipeline Dictionary
-
-## See Also
-
-- [B2C Commerce Script API Documentation](../dw_system/)
-- [ISML Expressions](./expressions.md)
-- [isset Element](./isset.md)
-- [SFRA Client-side JS Skill](../../ai-instructions/skills/sfcc-sfra-client-side-js/SKILL.md)
-- [Security Skill](../../ai-instructions/skills/sfcc-security/SKILL.md)
-- [Performance Skill](../../ai-instructions/skills/sfcc-performance/SKILL.md)