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 oneExplore ISML support
Scripting in ISML
Typed pdict from render calls, @pdict lines, template variables and the compatibility mode
Completion
Tags, attributes, values, template paths, live templates and postfix templates
Custom Tags
ismodule declarations, custom tag completion, the @param check and Extract Custom Tag
Template Navigation
Template links, gutter icons, Code Vision, overrides and Find Usages
Editing
Typing aids, Surround With, comments, folding, structure, intentions and refactorings
Inspections
Syntax, attributes, templates, routes, resources, output encoding and pdict checks
Formatting
Indentation and Full mode, the code style options and EditorConfig keys
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:
| Free | Needs a license or trial |
|---|---|
| The file type, parsing, highlighting, tag colors and rainbow colors of template variables | Completion of tags, attributes, values, template paths and scripts |
| Typing aids, Smart Enter, Surround With and comments | Quick documentation |
| Folding, the Structure view and breadcrumbs | Typed pdict, name resolution and the pdict and variable colors in ${...} and <isscript> |
| Live and postfix templates, without their computed values | Template, custom tag and route links, gutter icons, Code Vision and inlay hints |
| The checks that read only the template and the tag catalog | Find Usages of templates and pdict members, and renaming overridden copies |
| Formatting and the New ISML File dialog | The 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:
| Task | Time |
|---|---|
| Parsing a 100 KB template | 19 ms |
| Typing, per character | 4.5 ms |
Completion after ${pdict. | 26 ms |
Building every pdict of a 1,400-template project | Under 1 s |
| Indexing 3,010 templates in 40 cartridges | 356 ms |
| Find Usages of a template included 300 times | 28 ms |
| Changing the cartridge path | 6.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
| Option | What it does |
|---|---|
| Modules files | File 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 target | Which 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 mode | Shown 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 comments | Off. On writes <!-- --> for lines of plain markup, see Editing |
| Show a banner on overridden templates and on templates outside the cartridge path | On, for you only. Show dismissed banners again brings back the banners you closed |
| Dropped scripts and styles | SFRA assets calls (default) or Tags, see Editing |
| Dim templates overridden for the active site in the Project view | Off, 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:
| Hint | Group | Default | Shows |
|---|---|---|---|
| ISML variable types | Types | On | The type after the names that <isset> and <isloop> declare |
| ISML template cartridge | Other | Off | The 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 encoding | Other | Off | The 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.memberin 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
| Symptom | What to do |
|---|---|
| No completion, links or gutter icons in templates | These need a license or trial, see Purchase & License |
Cannot resolve template on a template that exists | The template is in a cartridge that isn't linked, or not under templates/<locale>, see Cartridges |
| A template link opens the wrong copy | Change Template target, or check the cartridge path of the site, see Overrides |
| A custom tag is reported as unknown | The <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 errors | Set 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 HTML | Make sure *.isml belongs to ISML in Settings › Editor › File Types |