---
name: b2c-isml
description: Work with ISML templates in B2C Commerce. Use when writing storefront templates, using isprint/isset/isloop tags, understanding ISML expressions (${...}), or creating custom template modules. Covers tag syntax, expression language, and template includes.
---
# 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
In Stock
Pre-order
Out of Stock
```
### Loops
```html
${loopstate.count}. ${product.name}
Featured
```
**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
${productName}
```
**Scopes (required):** `page`, `request`, `session`, `pdict`
### Output
```html
```
### Include Templates
```html
```
### Decorator Pattern
**Base decorator (layouts/pagelayout.isml):**
```html
${pdict.pageTitle}
```
**Page using decorator:**
```html
${pdict.welcomeMessage}
```
## Expressions
Expressions use `${...}` syntax to embed dynamic values:
```html
${product.name}
${product.price.sales.value}
${product.getAvailabilityModel().isInStock()}
${pdict.myVariable}
${session.customer.firstName}
${request.httpParameterMap.pid.stringValue}
${price > 100 ? 'expensive' : 'affordable'}
${firstName + ' ' + lastName}
${quantity * unitPrice}
```
## Built-in Utilities
### URLUtils
```html
View
My Account
})
Home
```
### Resource (Localization)
```html
${Resource.msg('button.addtocart', 'product', null)}
${Resource.msgf('cart.items', 'cart', null, cartCount)}
```
### StringUtils
```html
${StringUtils.truncate(description, 100, '...')}
${StringUtils.formatNumber(quantity, '###,###')}
```
## Custom Modules
Define reusable custom tags in `util/modules.isml`:
```html
```
**Component template (components/productcard.isml):**
```html
${product.name}
${product.price.sales.formatted}
${product.rating} stars
```
## Caching
```html
```
**Place `` at the beginning of the template.**
## Content Type
```html
```
## Embedded Scripts
```html
var ProductMgr = require('dw/catalog/ProductMgr');
var product = ProductMgr.getProduct(pdict.pid);
var price = product.priceModel.price;
${price.toFormattedString()}
```
**Best Practice:** Keep `` blocks minimal. Move complex logic to controllers or helper scripts.
## Comments
```html
ISML comment - stripped from output.
Use for documentation and hiding sensitive info.
```
## Tag Location Constraints
Not all ISML tags can be used anywhere. Important constraints:
| Tag | Allowed Location |
|-----|------------------|
| `` | Must be before DOCTYPE declaration |
| `` | Must be before DOCTYPE declaration |
| `` | Only in `` |
| `` | Only in ``, inside `` |
| `` | Only in ``, inside `` |
| `` | Inside `` |
| `` | Must be within `` tags |
| `` | Only in `` |
Tags that can be used **anywhere**: ``, ``, ``, ``, ``, ``, ``, ``, ``, ``.
## Best Practices
1. **Use ``** instead of HTML comments for sensitive info
2. **Place `` 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 ``
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