ISML Navigation

The ISML server connects a template to the rest of your project, so you can move from an include to its target and from a custom tag to its template, find the templates that read a script module's exports, read tag documentation in place, and see a template's structure at a glance

Template and custom tag links

Every template="…" value that matches a template is a document link, on <isinclude>, <isdecorate>, <ismodule>, or any other tag. Cmd-click it (Ctrl-click on Windows and Linux) to open the template. The path is matched in every cartridge and locale folder, so checkout/billing finds templates/default/checkout/billing.isml as well as a localized copy such as templates/fr_FR/checkout/billing.isml

When more than one template matches, the Select ISML File quick pick lists each copy with its cartridge and folder, and you choose which one to open. Copies are listed in cartridge path order, with the default locale first within each cartridge. The cartridge path on the instance still decides which copy renders at runtime

Custom tags link the same way: Cmd-click a tag such as <isproducttile> to open the template its <ismodule> names. See Custom tags and modules

A few rules decide which values become links:

• The value can be in double or single quotes, and every template value links, even several on one line
• A value that contains ${, such as ${pdict.template}, is an expression and is not linked
• A leading / is ignored and .isml is added, so /checkout/billing and checkout/billing.isml open the same template
• The whole path below the locale folder must match, so billing does not open checkout/billing.isml
• Only an attribute named template counts, so data-template is not a link

Go to Definition (F12) follows the same paths and custom tag names. When one template matches, it opens. When several match, VS Code lists them in a peek, so you can preview each copy before you open one. Inside expressions and script blocks, Go to Definition works on script symbols, see Scripting in ISML

Custom tags are read again when a module file is added, changed or deleted, and when you change intellij-sfcc.isml.modules.files, so a new tag links without a restart. See Custom tags and modules

Find template usages from scripts

Templates that load a script module with require() count as users of its exports. Run Go to References (Shift+F12) or Find All References (Shift+Option+F12 on macOS, Shift+Alt+F12 on Windows and Linux) on a property of the module's module.exports, and the results list each template line that reads it, next to the controllers and scripts that use the same export

module.exports = {
    ACTION_TYPES: {
        VOUCHER: 'voucher',
        GIFT_CARD: 'giftCard'
    },
    MAX_CODES: 5
};

<isscript>
    var constants = require('*/cartridge/scripts/checkout/constants');
    var isVoucher = pdict.type === constants.ACTION_TYPES.VOUCHER;
</isscript>
<input name="type" value="${constants.ACTION_TYPES.VOUCHER}" type="hidden" />

References to ACTION_TYPES include both lines of voucherForm.isml: the read in the <isscript> block and the one in the ${ … } expression. Click a template result in the peek to preview the template, and double-click it to open the template at that reference

• A template is listed when an <isscript> block assigns the module to a variable with require() and the template reads the property through that variable, as constants.ACTION_TYPES or constants['ACTION_TYPES'], in a script block or an expression
• A value that only reaches the template through pdict does not tie the template to the module, so that template is not listed
• References work on top-level export names. Starting on a nested key such as VOUCHER lists the references of ACTION_TYPES, the export that contains it
• Run the search in the module or in a script that uses the export. Started on the property inside a template, it does not cover every file that uses the export

The same search from scripts is described in References across module boundaries. For variables declared inside a template, see Template variable navigation

Hover

Hover an ISML tag name, in its start or end tag, to read its documentation, such as the purpose, syntax, attributes, and notes of <isloop>, with a B2C Commerce Documentation link at the end. Hovering an attribute name describes the attribute and its allowed data type, and hovering a character entity such as © shows the character and its Unicode code point

Inside ${ … } and <isscript>, the scripting engine shows the script hover with dw.* signatures and JSDoc, see Scripting in ISML

Outline and breadcrumbs

The server provides document symbols, so the Outline view and the breadcrumbs follow the template's structure. ISML tags are named by what they do: isset with its variable, isloop with var in items, isinclude and isdecorate with their template, iscomponent with its pipeline, and isif and iselseif with their condition. Other tags show as tag#id.class

Matching tags and rename

Put the caret in a tag name and the start and end tag of that element are highlighted. Press F2 (Rename Symbol) in a tag name to rename both at once, for example <div> to <section>

Tag rename edits the markup tags of the current template only. It does not rename a custom tag's <ismodule> declaration. For variables, see the next section

Rename a template variable

Press F2 (Rename Symbol) on a template variable, in its <isset name="…"> or <isloop var="…" status="…"> value, in a ${ … } expression or in an <isscript> block. The rename edits the declaration and every use that Find References lists

• Across templates. When another template reads or sets the variable, such as an included template or a custom tag's template, every connected template is edited. Templates that only share the name are left alone, see Variables across templates
• In one template. A variable no other template uses is matched by name in its own template, so a property with the same name, such as pdict.badge, is renamed too. Press Shift+Enter in the rename box to preview the edits first
• The new name must be a valid JavaScript identifier, otherwise nothing is renamed

Folding and selection

• Folding - fold an element from its start tag to the line before its end tag, a multi-line <iscomment> or <!-- --> comment, or a region between <!-- #region --> and <!-- #endregion -->. Fold and Unfold use ⌥⌘[ and ⌥⌘] on macOS or Ctrl+Shift+[ and Ctrl+Shift+] on Windows and Linux, and Fold All and Unfold All use ⌘K ⌘0 and ⌘K ⌘J on macOS or Ctrl+K Ctrl+0 and Ctrl+K Ctrl+J on Windows and Linux
• Expand Selection (⌃⇧⌘→ on macOS, Shift+Alt+Right on Windows and Linux) grows the selection from a word to the attribute value, the attribute, the tag, the line, and then each enclosing element. Shrink Selection (⌃⇧⌘← on macOS, Shift+Alt+Left on Windows and Linux) steps back

Related

Custom Tags & Modules

What the custom-tag links point to

Scripting in ISML

Hover, definitions, and references for expression symbols and template variables

Scripting LSP Navigation

Go-to-definition and references across .ds and .js