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'.
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:
<!-- Set a variable (scope is required) --><issetname="productName"value="${product.name}"scope="page"/><!-- Use the variable --><span>${productName}</span><!-- Remove a variable --><isremovename="productName"scope="page"/>
Scopes (required):page, request, session, pdict
Output
<!-- Basic output (HTML encoded by default) --><isprintvalue="${product.name}"/><!-- Unencoded output (use carefully) --><isprintvalue="${htmlContent}"encoding="off"/><!-- Formatted number --><isprintvalue="${price}"style="CURRENCY"/><!-- Formatted date --><isprintvalue="${order.creationDate}"style="DATE_SHORT"/>
Include Templates
<!-- Include local template --><isincludetemplate="product/components/price"/><!-- Include with URL (remote include) --><isincludeurl="${URLUtils.url('Product-GetPrice', 'pid', product.ID)}"/>
Decorator Pattern
Base decorator (layouts/pagelayout.isml):
<!DOCTYPE html><html><head><title>${pdict.pageTitle}</title></head><body><header><isincludetemplate="components/header"/></header><main><isreplace/><!-- Content inserted here --></main><footer><isincludetemplate="components/footer"/></footer></body></html>
<!-- Get localized string -->
${Resource.msg('button.addtocart', 'product', null)}
<!-- With parameters -->
${Resource.msgf('cart.items', 'cart', null, cartCount)}
StringUtils
<!-- Truncate text -->
${StringUtils.truncate(description, 100, '...')}
<!-- Format number -->
${StringUtils.formatNumber(quantity, '###,###')}
Custom Modules
Define reusable custom tags in util/modules.isml:
<!-- Definition in util/modules.isml --><ismoduletemplate="components/productcard"name="productcard"attribute="product"attribute="showPrice"attribute="showRating"/><!-- Usage in any template --><isincludetemplate="util/modules"/><isproductcardproduct="${product}"showPrice="${true}"showRating="${true}"/>
<!-- Cache for 24 hours --><iscachetype="relative"hour="24"/><!-- Daily cache (expires at midnight) --><iscachetype="daily"hour="0"minute="0"/><!-- Vary cache by parameter --><iscachetype="relative"hour="1"varyby="price_promotion"/>
Place <iscache> at the beginning of the template.
Content Type
<!-- Set content type (must be first in template) --><iscontenttype="text/html"charset="UTF-8"/><!-- For JSON responses --><iscontenttype="application/json"charset="UTF-8"/><!-- For XML --><iscontenttype="application/xml"charset="UTF-8"/>
Embedded Scripts
<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 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
Use <iscomment> instead of HTML comments for sensitive info
Place <iscontent> first in templates that need it
Define modules in util/modules.isml for consistency
Keep templates simple - move logic to controllers/helpers
