Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 28 ยท Controllers, Models and Templates

ISML Templates

Learn ISML, the template language of Salesforce Commerce Cloud: isprint, isif, isloop, isinclude, isdecorate, remote includes, Resource.msg and output encoding against XSS.

ISML (Internet Store Markup Language) is the template language of B2C Commerce. An ISML file is HTML with extra tags that start with is, such as <isprint>, <isif> and <isloop>, plus ${...} expressions that read data from the controller. Every storefront page you see on an SFRA site is an ISML template rendered after a controller route finished.

Templates look simple, and that is their risk: output encoding, caching tags and includes all live in the markup, and a mistake in any of them ships to every shopper. This lesson covers the tags you will use daily, how pages are assembled from includes and decorators, how text is localized, and how to avoid cross-site scripting.

ISML runs only on the platform, so real templates here are read-only. The runnable examples are stand-ins: a tiny renderer for isprint, isif and isloop that shows how encoding works, and an encoder comparison. The real engine supports many more tags and has its own expression evaluator.

Where templates live and what they receive

Templates sit in cartridge/templates/default/ (with locale-specific folders next to default). A controller names one without the extension: res.render('product/detail', data) renders templates/default/product/detail.isml. Because template lookup follows the cartridge path, an overlay cartridge can replace a base template just by providing the same path.

Inside a template, the data your route prepared is available as pdict (the pipeline dictionary, a name from the pipeline days):

HTML
<!-- Read-only: templates/default/product/detail.isml (simplified) -->
<isdecorate template="common/layout/page">
  <h1><isprint value="${pdict.product.productName}" encoding="on" /></h1>

  <isif condition="${pdict.product.onSale}">
    <span class="badge"><isprint value="${Resource.msg('label.sale', 'product', null)}" /></span>
  </isif>

  <ul>
    <isloop items="${pdict.product.images}" var="image">
      <li><img src="${image.url}" alt="${image.alt}"></li>
    </isloop>
  </ul>
</isdecorate>

The tags you use every day

Tag Purpose
<isprint value="${...}" /> Output a value, encoded by default
<isif condition="${...}">, <iselseif>, <iselse> Conditions
<isloop items="${...}" var="x" status="loopstate"> Iterate; loopstate.first, .last, .count and .index help
<isset name="x" value="${...}" scope="page" /> Set a variable (page, request, session, pdict)
<iscomment> ... </iscomment> Comment that never reaches the browser
<isinclude template="..." /> Include another template (local include)
<isinclude url="${URLUtils.url('Cart-MiniCart')}" /> Remote include: a separate request
<isdecorate template="..."> ... </isdecorate> Wrap content in a layout
<isreplace /> The slot inside a decorator where the wrapped content goes
<iscache ... /> Page-cache settings (see Caching and Performance)
<isscript> ... </isscript> Inline server-side script; use sparingly
<isslot id="..." ... /> Render a content slot configured in Business Manager

Keep logic out of templates where you can. A template should decide how to show data, not calculate it. Calculations belong in models and helpers.

Includes and decorators

Pages are assembled from parts. A decorator is a layout template (header, footer, scripts) that wraps content. The page says <isdecorate template="common/layout/page">, and the decorator contains <isreplace/> at the spot where the page body goes.

HTML
<!-- Read-only: templates/default/common/layout/page.isml (simplified) -->
<!DOCTYPE html>
<html>
  <head><isinclude template="common/htmlHead" /></head>
  <body>
    <isinclude template="components/header/pageHeader" />
    <main><isreplace /></main>
    <isinclude template="components/footer/pageFooter" />
  </body>
</html>
flowchart TD
    Page["product/detail.isml"] -->|"isdecorate"| Layout["common/layout/page.isml"]
    Layout --> Head["htmlHead (local include)"]
    Layout --> Header["pageHeader (local include)"]
    Layout --> Slot["isreplace: the page body"]
    Layout --> Footer["pageFooter (local include)"]
    Header -.->|"isinclude url"| Mini["Cart-MiniCart<br/>(remote include)"]

A page is wrapped by a decorator, which pulls in local includes; a remote include is a separate request.

A local include (template=) is pasted in at render time and shares the page's data. A remote include (url=) makes the platform issue a separate request to a controller route and insert the result. Remote includes exist for caching: the page can be cached for a day while the mini cart include stays fresh or personalized. The cost is one extra request per include, so use them for the few fragments that really differ.

Localized text with Resource.msg

Never hard-code visible text. Put it in .properties files under the cartridge's templates/resources folder (one per locale, such as product_fr_FR.properties) and read it with Resource.msg(key, bundle, default):

HTML
<!-- Read-only -->
<isprint value="${Resource.msg('label.addtocart', 'product', null)}" />
<isprint value="${Resource.msgf('label.items', 'cart', null, pdict.count)}" />

The bundle name is the file name without the locale suffix and the extension. msgf fills -style placeholders. Using resources lets translators work without touching templates and lets the platform pick the right language for the shopper's locale.

Output encoding and XSS

Cross-site scripting (XSS) happens when user-controlled text reaches a page as markup. A product review with <script> in it, a search term echoed on the results page, a name typed into a form: if these are printed without encoding, the browser runs them.

<isprint> encodes by default for HTML content. You turn it off with encoding="off", which should be a rare, reviewed exception (for example for HTML from a trusted content asset). Other values choose a context: HTML content, quoted attributes, JavaScript strings, URIs and so on.

Two rules keep you safe:

  1. Print through isprint and keep encoding on. Check how ${...} expressions written directly in attributes or in the page text behave for your compatibility mode and instance, and do not rely on automatic encoding that you have not verified.
  2. Encode for the right context. HTML-content encoding is not enough inside an attribute or a script block.
JS A tiny ISML-style renderer and why encoding matters (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The product name and the quoted tag are encoded, while the note is printed raw because the template said encoding="off". If that note came from a shopper instead of a trusted editor, this single attribute would be a security hole.

Encoding is about context

The same hostile string needs different treatment depending on where it lands. This stand-in compares four encoders and shows what happens when you pick the wrong one.

JS One input, four contexts (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last line is the lesson: a content encoder leaves the double quote alone, so the attribute still closes early and the page structure is broken. Security is covered further in Security, Sessions and Compliance.

Habits worth keeping

  • Keep templates small and compose them with includes and decorators.
  • Prefix IDs and classes consistently, and avoid inline <isscript> blocks beyond trivial ones.
  • Use Resource.msg for all visible text.
  • Add <iscache> deliberately and check what in the template varies per shopper.
  • Review every encoding="off" in code review.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is pdict inside an ISML template?

    pdict holds the data the route passed to res.render plus viewData.
  2. 2. What is the difference between a local and a remote include?

    Remote includes call a controller route separately, so a fragment such as the mini cart can have its own cache rules.
  3. 3. When should isprint use encoding="off"?

    Turning encoding off removes XSS protection, so it is for trusted content only.
  4. 4. Why use Resource.msg for visible text?

    Resource bundles support translation by locale and keep text out of markup.
  5. 5. Which tag marks where a decorator inserts the wrapped page content?

    isreplace is the placeholder inside the decorator template.

Summary

  • ISML is HTML plus is... tags and ${} expressions; controllers hand data to it as pdict.
  • Core tags: isprint, isif, isloop, isset, isinclude, isdecorate/isreplace, iscache, isslot.
  • Local includes share the page; remote includes are separate requests that allow different caching.
  • Use Resource.msg for text and keep logic in models and helpers.
  • Print through isprint with encoding on, pick the encoder that matches the context, and treat encoding="off" as a review item.

Next: Forms, Validation and CSRF