@salesforce/b2c-cli 2.3.1 → 2.5.0

package/content/guidance/b2c/b2c-isml/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: b2c-isml
+description: Build ISML templates with isprint, isset, isloop, isdecorate, isinclude tags, and ${...} expression syntax. Use this skill whenever the user needs to write or debug storefront templates, create decorator layouts with isreplace, build reusable template modules, control HTML encoding in output, or use ISML expression language for dynamic content. Also use when fixing template rendering issues -- even if they just say 'loop through products in the template' or 'my HTML is getting escaped'.
+---
+
+# ISML Skill
+
+This skill guides you through creating and working with ISML (Isomorphic Markup Language) templates in Salesforce B2C Commerce. ISML templates combine HTML with dynamic server-side tags.
+
+## Overview
+
+ISML templates are server-side templates that generate HTML. They use special tags prefixed with `is` and expressions in `${...}` syntax to embed dynamic content.
+
+## File Location
+
+Templates reside in the cartridge's `templates` directory:
+
+```
+/my-cartridge
+    /cartridge
+        /templates
+            /default                    # Default locale
+                /product
+                    detail.isml
+                    tile.isml
+                /home
+                    homepage.isml
+                /util
+                    modules.isml        # Custom tag definitions
+            /fr_FR                      # French-specific templates
+                /product
+                    detail.isml
+```
+
+## Essential Tags
+
+### Conditional Logic
+
+```html
+<isif condition="${product.available}">
+    <span class="in-stock">In Stock</span>
+<iselseif condition="${product.preorderable}">
+    <span class="preorder">Pre-order</span>
+<iselse>
+    <span class="out-of-stock">Out of Stock</span>
+</isif>
+```
+
+### Loops
+
+```html
+<isloop items="${products}" var="product" status="loopstate">
+    <div class="product ${loopstate.odd ? 'odd' : 'even'}">
+        <span>${loopstate.count}. ${product.name}</span>
+        <isif condition="${loopstate.first}">
+            <span class="badge">Featured</span>
+        </isif>
+    </div>
+</isloop>
+```
+
+**Loop status properties:**
+- `count` - Iteration number (1-based)
+- `index` - Current index (0-based)
+- `first` - Boolean, true on first iteration
+- `last` - Boolean, true on last iteration
+- `odd` - Boolean, true on odd iterations
+- `even` - Boolean, true on even iterations
+
+### Variables
+
+```html
+<!-- Set a variable (scope is required) -->
+<isset name="productName" value="${product.name}" scope="page"/>
+
+<!-- Use the variable -->
+<span>${productName}</span>
+
+<!-- Remove a variable -->
+<isremove name="productName" scope="page"/>
+```
+
+**Scopes (required):** `page`, `request`, `session`, `pdict`
+
+### Output
+
+```html
+<!-- Basic output (HTML encoded by default) -->
+<isprint value="${product.name}"/>
+
+<!-- Unencoded output (use carefully) -->
+<isprint value="${htmlContent}" encoding="off"/>
+
+<!-- Formatted number -->
+<isprint value="${price}" style="CURRENCY"/>
+
+<!-- Formatted date -->
+<isprint value="${order.creationDate}" style="DATE_SHORT"/>
+```
+
+### Include Templates
+
+```html
+<!-- Include local template -->
+<isinclude template="product/components/price"/>
+
+<!-- Include with URL (remote include) -->
+<isinclude url="${URLUtils.url('Product-GetPrice', 'pid', product.ID)}"/>
+```
+
+### Decorator Pattern
+
+**Base decorator (layouts/pagelayout.isml):**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>${pdict.pageTitle}</title>
+</head>
+<body>
+    <header>
+        <isinclude template="components/header"/>
+    </header>
+    <main>
+        <isreplace/>  <!-- Content inserted here -->
+    </main>
+    <footer>
+        <isinclude template="components/footer"/>
+    </footer>
+</body>
+</html>
+```
+
+**Page using decorator:**
+```html
+<isdecorate template="layouts/pagelayout">
+    <isslot id="home-banner" context="global"/>
+    <div class="homepage-content">
+        <h1>${pdict.welcomeMessage}</h1>
+    </div>
+</isdecorate>
+```
+
+## Expressions
+
+Expressions use `${...}` syntax to embed dynamic values:
+
+```html
+<!-- Property access -->
+${product.name}
+${product.price.sales.value}
+
+<!-- Method calls -->
+${product.getAvailabilityModel().isInStock()}
+
+<!-- Built-in objects -->
+${pdict.myVariable}           <!-- Controller data -->
+${session.customer.firstName} <!-- Session data -->
+${request.httpParameterMap.pid.stringValue}
+
+<!-- Operators -->
+${price > 100 ? 'expensive' : 'affordable'}
+${firstName + ' ' + lastName}
+${quantity * unitPrice}
+```
+
+## Built-in Utilities
+
+### URLUtils
+
+```html
+<!-- Controller URL -->
+<a href="${URLUtils.url('Product-Show', 'pid', product.ID)}">View</a>
+
+<!-- HTTPS URL -->
+<a href="${URLUtils.https('Account-Show')}">My Account</a>
+
+<!-- Static resource -->
+<img src="${URLUtils.staticURL('/images/logo.png')}" alt="Logo"/>
+
+<!-- Absolute URL -->
+<a href="${URLUtils.abs('Home-Show')}">Home</a>
+```
+
+### Resource (Localization)
+
+```html
+<!-- Get localized string -->
+${Resource.msg('button.addtocart', 'product', null)}
+
+<!-- With parameters -->
+${Resource.msgf('cart.items', 'cart', null, cartCount)}
+```
+
+### StringUtils
+
+```html
+<!-- Truncate text -->
+${StringUtils.truncate(description, 100, '...')}
+
+<!-- Format number -->
+${StringUtils.formatNumber(quantity, '###,###')}
+```
+
+## Custom Modules
+
+Define reusable custom tags in `util/modules.isml`:
+
+```html
+<!-- Definition in util/modules.isml -->
+<ismodule template="components/productcard"
+          name="productcard"
+          attribute="product"
+          attribute="showPrice"
+          attribute="showRating"/>
+
+<!-- Usage in any template -->
+<isinclude template="util/modules"/>
+<isproductcard product="${product}" showPrice="${true}" showRating="${true}"/>
+```
+
+**Component template (components/productcard.isml):**
+```html
+<div class="product-card">
+    <img src="${product.image.url}" alt="${product.name}"/>
+    <h3>${product.name}</h3>
+    <isif condition="${pdict.showPrice}">
+        <span class="price">${product.price.sales.formatted}</span>
+    </isif>
+    <isif condition="${pdict.showRating && product.rating}">
+        <span class="rating">${product.rating} stars</span>
+    </isif>
+</div>
+```
+
+## Caching
+
+```html
+<!-- Cache for 24 hours -->
+<iscache type="relative" hour="24"/>
+
+<!-- Daily cache (expires at midnight) -->
+<iscache type="daily" hour="0" minute="0"/>
+
+<!-- Vary cache by parameter -->
+<iscache type="relative" hour="1" varyby="price_promotion"/>
+```
+
+**Place `<iscache>` at the beginning of the template.**
+
+## Content Type
+
+```html
+<!-- Set content type (must be first in template) -->
+<iscontent type="text/html" charset="UTF-8"/>
+
+<!-- For JSON responses -->
+<iscontent type="application/json" charset="UTF-8"/>
+
+<!-- For XML -->
+<iscontent type="application/xml" charset="UTF-8"/>
+```
+
+## Embedded Scripts
+
+```html
+<isscript>
+    var ProductMgr = require('dw/catalog/ProductMgr');
+    var product = ProductMgr.getProduct(pdict.pid);
+    var price = product.priceModel.price;
+</isscript>
+
+<span>${price.toFormattedString()}</span>
+```
+
+**Best Practice:** Keep `<isscript>` blocks minimal. Move complex logic to controllers or helper scripts.
+
+## Comments
+
+```html
+<!-- HTML comment (visible in source) -->
+
+<iscomment>
+    ISML comment - stripped from output.
+    Use for documentation and hiding sensitive info.
+</iscomment>
+```
+
+## Tag Location Constraints
+
+Not all ISML tags can be used anywhere. Important constraints:
+
+| Tag | Allowed Location |
+|-----|------------------|
+| `<iscontent>` | Must be before DOCTYPE declaration |
+| `<isredirect>` | Must be before DOCTYPE declaration |
+| `<isprint>` | Only in `<body>` |
+| `<isbreak>` | Only in `<body>`, inside `<isloop>` |
+| `<iscontinue>` | Only in `<body>`, inside `<isloop>` |
+| `<isnext>` | Inside `<isloop>` |
+| `<isreplace>` | Must be within `<isdecorate>` tags |
+| `<isactivedatahead>` | Only in `<head>` |
+
+Tags that can be used **anywhere**: `<isif>`, `<isloop>`, `<isinclude>`, `<isset>`, `<isremove>`, `<iscache>`, `<iscomment>`, `<ismodule>`, `<iscookie>`, `<isstatus>`.
+
+## Best Practices
+
+1. **Use `<iscomment>`** instead of HTML comments for sensitive info
+2. **Place `<iscontent>` first** in templates that need it
+3. **Define modules** in `util/modules.isml` for consistency
+4. **Keep templates simple** - move logic to controllers/helpers
+5. **Use decorators** for consistent page layouts
+6. **Enable caching** on cacheable pages with `<iscache>`
+7. **Encode output** - default encoding prevents XSS
+
+## Detailed Reference
+
+For comprehensive tag documentation:
+- [Tags Reference](references/TAGS.md) - All ISML tags with examples
+- [Expressions Reference](references/EXPRESSIONS.md) - Expression syntax and built-in functions

package/content/guidance/b2c/b2c-isml/references/EXPRESSIONS.md

@@ -0,0 +1,366 @@
+# ISML Expressions Reference
+
+Expression syntax and built-in functions available in ISML templates.
+
+## Expression Syntax
+
+Expressions use `${...}` syntax:
+
+```html
+${expression}
+```
+
+## Property Access
+
+```html
+<!-- Simple property -->
+${product.name}
+
+<!-- Nested property -->
+${product.price.sales.value}
+
+<!-- Method call -->
+${product.getName()}
+
+<!-- Chained access -->
+${customer.profile.addressBook.preferredAddress.city}
+```
+
+## Built-in Objects
+
+### pdict
+
+Data passed from controller:
+
+```html
+<!-- Controller: res.render('template', { myVar: 'value' }) -->
+${pdict.myVar}
+```
+
+### session
+
+Session data:
+
+```html
+${session.sessionID}
+${session.customer}
+${session.customer.authenticated}
+${session.customer.profile.firstName}
+${session.currency.currencyCode}
+${session.custom.myCustomAttribute}
+```
+
+### request
+
+HTTP request:
+
+```html
+${request.httpMethod}
+${request.httpHost}
+${request.httpPath}
+${request.httpHeaders}
+${request.httpParameterMap.paramName.stringValue}
+${request.locale}
+${request.isHttpSecure()}
+```
+
+### response
+
+HTTP response (limited in templates):
+
+```html
+${response.writer}
+```
+
+### customer
+
+Current customer:
+
+```html
+${customer.authenticated}
+${customer.registered}
+${customer.ID}
+${customer.profile.firstName}
+${customer.profile.email}
+```
+
+## Operators
+
+### Arithmetic
+
+```html
+${price * quantity}
+${total + tax}
+${price - discount}
+${total / count}
+${value % 2}  <!-- Modulo -->
+```
+
+### Comparison
+
+```html
+${price > 100}
+${quantity >= 1}
+${price < maxPrice}
+${stock <= threshold}
+${product.ID == 'ABC123'}
+${status != 'CANCELLED'}
+```
+
+### Logical
+
+```html
+${inStock && available}
+${isNew || onSale}
+${!outOfStock}
+```
+
+### Ternary
+
+```html
+${inStock ? 'Available' : 'Out of Stock'}
+${customer.authenticated ? customer.profile.firstName : 'Guest'}
+```
+
+### String Concatenation
+
+```html
+${firstName + ' ' + lastName}
+${'Product: ' + product.name}
+```
+
+### Null Check
+
+```html
+${product != null ? product.name : 'Unknown'}
+${empty(products) ? 'No products' : products.length + ' products'}
+```
+
+## Built-in Functions
+
+### empty()
+
+Check if null, empty string, or empty collection:
+
+```html
+<isif condition="${empty(products)}">
+    No products found
+</isif>
+
+<isif condition="${!empty(customer.profile)}">
+    Welcome, ${customer.profile.firstName}
+</isif>
+```
+
+## Utility Classes
+
+### URLUtils
+
+Generate URLs:
+
+```html
+<!-- Controller URL -->
+${URLUtils.url('Controller-Action')}
+${URLUtils.url('Product-Show', 'pid', product.ID)}
+${URLUtils.url('Search-Show', 'q', searchTerm, 'page', pageNum)}
+
+<!-- HTTPS URL -->
+${URLUtils.https('Account-Show')}
+${URLUtils.https('Checkout-Start')}
+
+<!-- HTTP URL -->
+${URLUtils.http('Home-Show')}
+
+<!-- Absolute URL -->
+${URLUtils.abs('Home-Show')}
+${URLUtils.absStatic('/images/logo.png')}
+
+<!-- Static resource -->
+${URLUtils.staticURL('/css/style.css')}
+${URLUtils.staticURL(URLUtils.CONTEXT_CATALOG, '', '/images/product.jpg')}
+
+<!-- Web root -->
+${URLUtils.webRoot()}
+${URLUtils.httpWebRoot()}
+${URLUtils.httpsWebRoot()}
+
+<!-- Home URL -->
+${URLUtils.home()}
+${URLUtils.httpHome()}
+${URLUtils.httpsHome()}
+
+<!-- Continue URL (current page) -->
+${URLUtils.continueURL()}
+```
+
+### Resource
+
+Localized strings:
+
+```html
+<!-- Simple message -->
+${Resource.msg('key.name', 'bundlename', null)}
+
+<!-- With fallback -->
+${Resource.msg('key.name', 'bundlename', 'Default Value')}
+
+<!-- With parameters -->
+${Resource.msgf('cart.itemcount', 'cart', null, itemCount)}
+${Resource.msgf('greeting', 'common', null, firstName, lastName)}
+```
+
+### StringUtils
+
+String manipulation:
+
+```html
+<!-- Truncate -->
+${StringUtils.truncate(description, 100, '...')}
+
+<!-- Pad -->
+${StringUtils.pad(orderNumber, 10)}
+
+<!-- Trim -->
+${StringUtils.trim(input)}
+
+<!-- Format -->
+${StringUtils.formatNumber(quantity, '###,###')}
+${StringUtils.formatInteger(count)}
+${StringUtils.formatMoney(price)}
+
+<!-- Encoding -->
+${StringUtils.stringToHtml(text)}
+${StringUtils.encodeString(text, 'UTF-8')}
+```
+
+### dw.util.Locale
+
+Locale information:
+
+```html
+${new dw.util.Locale(request.locale).displayCountry}
+${new dw.util.Locale(request.locale).displayLanguage}
+```
+
+## Date/Time
+
+### Formatting Dates
+
+```html
+<!-- Using isprint -->
+<isprint value="${order.creationDate}" style="DATE_SHORT"/>
+<isprint value="${order.creationDate}" formatter="yyyy-MM-dd HH:mm:ss"/>
+
+<!-- Using StringUtils -->
+${StringUtils.formatCalendar(new dw.util.Calendar(), 'yyyy-MM-dd')}
+```
+
+### Current Date
+
+```html
+<isscript>
+    var now = new Date();
+    var calendar = new dw.util.Calendar();
+</isscript>
+${now}
+${calendar.time}
+```
+
+## Collection Operations
+
+### Iteration
+
+```html
+<isloop items="${products}" var="product" status="st">
+    ${st.count}: ${product.name}
+</isloop>
+```
+
+### Size/Length
+
+```html
+${products.length}
+${products.size()}
+${basket.productLineItems.length}
+```
+
+### Check Contents
+
+```html
+<isif condition="${products.length > 0}">
+    Found ${products.length} products
+</isif>
+
+<isif condition="${empty(cart.items)}">
+    Cart is empty
+</isif>
+```
+
+## Common Patterns
+
+### Null-safe Access
+
+```html
+<!-- Check before access -->
+<isif condition="${product && product.brand}">
+    ${product.brand.displayValue}
+</isif>
+
+<!-- Ternary fallback -->
+${product.brand ? product.brand.displayValue : 'Unknown Brand'}
+```
+
+### Default Values
+
+```html
+${quantity || 1}
+${customer.profile.firstName || 'Guest'}
+```
+
+### Conditional Classes
+
+```html
+<div class="product ${product.available ? 'in-stock' : 'out-of-stock'}">
+<li class="${loopstatus.first ? 'first' : ''} ${loopstatus.last ? 'last' : ''}">
+```
+
+### Price Formatting
+
+```html
+<!-- Formatted price -->
+${product.priceModel.price.toFormattedString()}
+
+<!-- Raw value -->
+${product.priceModel.price.value}
+
+<!-- Currency code -->
+${product.priceModel.price.currencyCode}
+```
+
+### Product Images
+
+```html
+<!-- Primary image -->
+${product.getImage('large').URL}
+${product.getImage('large').absURL}
+${product.getImage('large').alt}
+
+<!-- Image with fallback -->
+<isif condition="${product.getImage('large')}">
+    <img src="${product.getImage('large').URL}" alt="${product.name}"/>
+<iselse>
+    <img src="${URLUtils.staticURL('/images/no-image.png')}" alt="No image"/>
+</isif>
+```
+
+### Localized Attributes
+
+```html
+<!-- Display value for localized attribute -->
+${product.custom.myAttribute}
+${product.brand.displayValue}
+
+<!-- Enum value -->
+${product.custom.productType.value}
+${product.custom.productType.displayValue}
+```