A template path in ISML names a file the server looks up along the cartridge path, and the plugin resolves it the same way. Every template value is a link, the first line of a template shows who renders and includes it, and overridden copies point to each other
Sandbox 01
version2
productDetails.isml
Global scopetemplate path is a link that follows the linked cartridges. The gutter icon of <isdecorate> lists each copy of the decorator, and Cmd+Click on an include opens the templateTemplate links
Cmd+Click (Ctrl+Click) or Go to Declaration (Cmd+B, Ctrl+B) on the template value of <isinclude>, <isdecorate> or <ismodule> opens the template. The same works in scripts, for example on res.render('product/productDetails')
| Rule | What it means |
|---|---|
| Paths are normalized | A leading / or ./ and the .isml extension don't matter, so /product/tile.isml and product/tile name the same template |
| Case-sensitive | Product/Tile doesn't find product/tile.isml. The inspection says which file you probably meant, see Inspections |
| Locale folders | The default folder comes first, then the other locale folders by name |
| Cartridge order | A path resolves through the linked cartridges. Template target in the ISML settings decides which copy opens first |
| Dynamic paths | A path with ${...} becomes a pattern, so a template that matches it still counts that include or render call in Included by, Rendered by and Find Usages |
When a path exists in several cartridges, the click opens the copy that wins and Go to Implementation (Cmd+Alt+B, Ctrl+Alt+B) lists every copy
Other ISML values link too:
- route names, for example
<iscomponent pipeline="Product-Tile">andURLUtils.url('Cart-Show') - slot and content asset ids in
<isslot id>and<iscontentasset aid> - static files in
URLUtils.staticURL('/images/logo.svg'),assets.addJs()andassets.addCss() - resource bundles and keys in
Resource.msg('button.addtocart', 'common', null)
Gutter icons
| Icon | Where | Tooltip | Click |
|---|---|---|---|
<isinclude template> | Includes product/components/breadcrumbs | Opens the template, or a Choose Template list when it exists in several cartridges | |
<isdecorate> and <ismodule> | Navigate to template (2 cartridges) | Opens the template, or lists each copy | |
| First line | Rendered by Search.js, Tile.js | Lists the controllers and scripts whose render calls pick this copy | |
| First line | Included by productGrid.isml, wishlistGrid.isml +2 | Lists the templates that include, decorate with or declare this copy as a custom tag | |
| First line | Overrides product/productTile in app_storefront_base | Opens the copies this one hides | |
| First line | Overridden by app_custom; app_custom renders | Opens the copies that hide this one | |
<isreplace/> in a decorator | Decorates productDetails.isml, cart.isml +4 | Lists the templates that decorate with this one | |
<isdecorate> | Decorated by app_storefront_base/cartridge/templates/default/common/layout/page.isml | Opens the decorator |
A template counts as rendered or included only where the path resolves to this exact copy, so an overridden copy has no Rendered by icon. Each icon can be turned off in Settings › Editor › General › Gutter Icons
Code Vision
Code Vision adds a line of links above the template, in the ISML group of Settings › Editor › Inlay Hints › Code vision
| Entry | Where | Click |
|---|---|---|
| 6 usages | Above the first line | Find Usages for the template: render calls, includes, decorators and custom tag declarations |
| Rendered by Search.js, Tile.js | Above the first line | Opens the script, or lists them when there are several |
| 12 usages | Above each <ismodule> | Lists the templates that use the custom tag, see Custom Tags |
| 5 decorated templates | Above <isreplace/> | Lists the templates that decorate with this one |
Overrides
A template in a cartridge further right on the cartridge path is hidden by a copy with the same path further left. Opening a hidden copy shows a banner above the editor:
This template is overridden by app_custom, so app_custom renders product/productTile
Open override opens the copy that renders, Compare opens both in a diff and Dismiss hides the banner for this file. A template in a cartridge that isn't on the cartridge path of the site in scope says so instead: "This cartridge is not on the cartridge path of site RefArch, so product/productTile never renders from here"
- Go to Super (
Cmd+U,Ctrl+U) opens the copy this one overrides - When two open templates share a name, the editor tab adds the cartridge, as in
productTile.isml [app_custom] - Dim templates overridden for the active site in the Project view greys out hidden copies in the Project view. It's off by default
See Overrides for overriding scripts and templates in general
Find Usages
Find Usages (Alt+F7) on a template, or on its file in the Project view, groups the results by kind:
| Group | Example |
|---|---|
| Rendered by controller | res.render('product/gridTile', tileModel) in Search.js |
| Rendered by script | ISML.renderTemplate('mail/orderConfirmation', model) in a helper |
| Rendered by pipeline | A pipeline interaction node with the template |
| Included by | <isinclude template="product/gridTile" /> |
| Decorated by | <isdecorate template="common/layout/page"> |
| Declared as custom tag | <ismodule template="components/loyaltyBadge" name="loyaltybadge" /> |
| Custom tag usage | <isloyaltybadge product="${product}" /> |
Rename
Rename (Shift+F6) on a template renames the file and updates every path that names it, keeping each path's style: a leading / and the .isml extension stay where they were written. When the template has copies in other cartridges, Rename overriding and overridden templates opens Rename Templates in Other Cartridges, so the copies keep the same path