b2c-isml

Included with Lifetime

$97 forever

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'.

Web Dev

What this skill does


# 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 exampl

Files: 4

Size: 26.2 KB

Complexity: 45/100

Category: Web Dev

Source: https://github.com/salesforcecommercecloud/b2c-developer-tooling/tree/main/skills/b2c/skills/b2c-isml

Related in Web Dev

generating-lwc-components

Included

Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc/**/*.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use generating-apex), Aura components, or Visualforce.

Web Devscripts

tanstack-query

Included

Manage server state in React with TanStack Query v5. Set up queries with useQuery, mutations with useMutation, configure QueryClient caching strategies, implement optimistic updates, and handle infinite scroll with useInfiniteQuery. Use when: setting up data fetching in React projects, migrating from v4 to v5, or fixing object syntax required errors, query callbacks removed issues, cacheTime renamed to gcTime, isPending vs isLoading confusion, keepPreviousData removed problems.

Web Devscripts

document-processor-api

Included

Process documents with Nutrient DWS. Use when the user wants to generate PDFs from HTML or URLs, convert Office/images/PDFs, assemble or split packets, OCR scans, extract text/tables/key-value pairs, redact PII, watermark, sign, fill forms, optimize PDFs, or produce compliance outputs like PDF/A or PDF/UA. Triggers include convert to PDF, merge these PDFs, OCR this scan, extract tables, redact PII, sign this PDF, make this PDF/A, or linearize for web delivery.

Web Devscripts

nutrient-document-processing

Included

Web Devscripts

tanstack-query

Included

Manage server state in React with TanStack Query v5. Covers useMutationState, simplified optimistic updates, throwOnError, network mode (offline/PWA), and infiniteQueryOptions. Use when setting up data fetching, fixing v4→v5 migration errors (object syntax, gcTime, isPending, keepPreviousData), or debugging SSR/hydration issues with streaming server components.

Web Devscripts

accelint-nextjs-best-practices

Included

Next.js performance optimization and best practices. Use when writing Next.js code (App Router or Pages Router); implementing Server Components, Server Actions, or API routes; optimizing RSC serialization, data fetching, or server-side rendering; reviewing Next.js code for performance issues; fixing authentication in Server Actions; or implementing Suspense boundaries, parallel data fetching, or request deduplication.

Web Devscripts