Skip to Content

ISML

ISML as a native language in JetBrains IDEs - typed pdict, completion, custom tags, navigation, inspections and formatting, and what needs a license

ISML (.isml) is the server-side template language of Salesforce B2C Commerce. Intellij SFCC makes it a native IDE language with its own parser and no language server. Template data stays HTML (or XML and JSON per <iscontent type>), and ${...} and <isscript> are JavaScript with the B2C Script API behind them

pdict has the members the controller passes to res.render. Completion lists them with their types, and the documentation beside the list says which line sets each one

Explore ISML support

A native language

Every .isml file opens as the ISML file type . The plugin knows all 32 built-in tags with their attributes, values, encodings and deprecations. Tag names match in any case, as on B2C Commerce

The IDE's HTML support keeps working: tag matching, Emmet, CSS and JavaScript in <style> and <script>, and the HTML inspections, minus the false alarms ISML would raise

Free and licensed

A license change applies at once, without a restart:

FreeNeeds a license or trial
The file type, parsing, highlighting, tag colors and rainbow colors of template variablesCompletion of tags, attributes, values, template paths and scripts
Typing aids, Smart Enter, Surround With and commentsQuick documentation
Folding, the Structure view and breadcrumbsTyped pdict, name resolution and the pdict and variable colors in ${...} and <isscript>
Live and postfix templates, without their computed valuesTemplate, custom tag and route links, gutter icons, Code Vision and inlay hints
The checks that read only the template and the tag catalogFind Usages of templates and pdict members, and renaming overridden copies
Formatting and the New ISML File dialogThe checks that read other files, drag and drop, Extract Include, Extract Custom Tag and Inline Include

See Purchase & License for the trial

Works while the IDE indexes

Editing, highlighting, folding, formatting and the checks that read only the template work while the IDE indexes. Checks that read other files wait until indexing ends. Changes to the cartridge path, modules files and render calls update open editors without a restart

From the plugin's performance tests:

TaskTime
Parsing a 100 KB template19 ms
Typing, per character4.5 ms
Completion after ${pdict.26 ms
Building every pdict of a 1,400-template projectUnder 1 s
Indexing 3,010 templates in 40 cartridges356 ms
Find Usages of a template included 300 times28 ms
Changing the cartridge path6.6 ms

Settings

Options are in Settings › Languages & Frameworks › ISML. Project options are saved in .idea/intellij-sfcc-isml.xml, so the team can share them

OptionWhat it does
Modules filesFile names of templates whose custom tags every template sees. Empty reads intellij-sfcc.isml.modules.files from .vscode/settings.json, then uses modules.isml and module.isml
Template targetWhich copy a link opens. Current cartridge first (default) tries the template's own cartridge, then the cartridge path, as in VS Code. Runtime winner opens the copy B2C Commerce renders, the first on the cartridge path
Script compatibility modeShown here read-only. One mode covers templates, .ds and server .js files, and Change on the Digital Script page opens where it's set, see Digital Script settings
Comment template data with HTML commentsOff. On writes <!-- --> for lines of plain markup, see Editing
Show a banner on overridden templates and on templates outside the cartridge pathOn, for you only. Show dismissed banners again brings back the banners you closed
Dropped scripts and stylesSFRA assets calls (default) or Tags, see Editing
Dim templates overridden for the active site in the Project viewOff, for you only. The tooltip names the cartridge whose copy renders

The other ISML options sit with their features: Editor › Code Style › ISML for Formatting, Editor › Inspections › SFCC › ISML for Inspections, Editor › General › Code Folding › ISML, Editor › Live Templates › ISML and Editor › File and Code Templates

Colors and inlay hints

Settings › Editor › Color Scheme › ISML colors tags by category (control flow, output, composition) or one tag at a time, plus custom tags, attributes, template paths, unresolved paths, the ${ } delimiters, the embedded code background, pdict, template, session and loop variables, resource keys and bundles, and the underline of clickable paths, routes and keys. Default, Darcula, High contrast and Islands Dark have their own ISML colors. The pdict and variable colors inside ${...} and <isscript> need a license or trial

<isinclude>, <isdecorate> and custom tags have their own colors, so the templates a page pulls in stand out from the other tags. Custom tags are also italic. To give them the tag color again, select the tag on the ISML page and tick Inherit values from

With Semantic highlighting on in Settings › Editor › Color Scheme › Language Defaults, each template variable gets its own color at its <isset> or <isloop> and at every use. Rainbow colors are free and work while the IDE indexes

Settings › Editor › Inlay Hints has three ISML hints:

HintGroupDefaultShows
ISML variable typesTypesOnThe type after the names that <isset> and <isloop> declare
ISML template cartridgeOtherOffThe cartridge whose copy a template path renders, when it's another cartridge. Also when the cartridge is the template's own shows it after every path
ISML expression encodingOtherOffThe encoding of ${...} where HTML encoding doesn't fit, such as in a script, CSS, an event handler or a URL query

What isn't covered

  • There are no breakpoints in templates
  • Renaming pdict.member in a template doesn't rename the controller property, but renaming the controller property renames its template uses
  • Checks that read other files cover only templates in linked cartridges, and route checks only literal Controller-Action names
  • Slot ids link to their configuration only when the site import XML is in the project
  • The include depth limit of B2C Commerce, 20 nested templates and 16 nested URL includes, isn't checked

Troubleshooting

SymptomWhat to do
No completion, links or gutter icons in templatesThese need a license or trial, see Purchase & License
Cannot resolve template on a template that existsThe template is in a cartridge that isn't linked, or not under templates/<locale>, see Cartridges
A template link opens the wrong copyChange Template target, or check the cartridge path of the site, see Overrides
A custom tag is reported as unknownThe <ismodule> is in a file that isn't a modules file, or in a cartridge that isn't linked, see Custom Tags
Template literals are reported as errorsSet Script compatibility mode in Settings › Languages & Frameworks › Digital Script to your instance's mode. Modes before 22.7 have no template literals, see Compatibility mode
A .isml file opens as text or HTMLMake sure *.isml belongs to ISML in Settings › Editor › File Types

On this page