Skip to Content

SFCC Contracts

Completion and navigation for the strings that tie SFCC code together - routes, templates, resource keys, hooks, step types, forms and custom attributes

SFCC code is held together by strings such as 'Cart-Show', 'cart/cart' and 'button.checkout'. Intellij SFCC completes them from your project, and Cmd+Click (Ctrl+Click) opens the route, template, bundle key, hook, form or attribute behind them

Resource.msg keys complete from every .properties bundle with the locales that define them. Accepting fills in the bundle name too

Routes and controllers

CallThe stringCompletes
URLUtils.url, URLUtils.https, URLUtils.http, URLUtils.absThe full route, for example Cart-ShowEvery route of every linked cartridge: SFRA controllers, SiteGenesis exports.<Name> controllers and pipeline start nodes
new URLAction and helpers added in SFCC Route CallsThe full route, in the argument the rule namesEvery route of every linked cartridge
server.append, server.prepend, server.replaceA route of the same controller, for example ShowThe routes of the controller you extend
server.get, server.post, server.useThe route name you defineNothing, but Cmd+Click lists every other definition, append, prepend and replace of that route
app_custom/cartridge/controllers/Cart.js
server.extend(module.superModule);

server.append('Show', function (req, res, next) {
    res.setViewData({ continueUrl: URLUtils.url('Search-Show', 'cgid', 'root').toString() });
    next();
});

Route items carry the route icon . To find a route from anywhere, use the B2C Entry Points tab of Search Everywhere

Routes come from .js, .ds and .ts files (not .d.ts) in cartridge/controllers and from pipeline XML in cartridge/pipelines. For typed req and res, middleware and view data, see SFRA Controllers

Templates

CallTemplate argument
res.render, app.getView().render, ISML.renderTemplate, new Template(...)First
renderTemplateHelper.getRenderedHtml, emailHelpers.sendEmailSecond

Paths complete relative to templates/<locale>, without .isml. A known template gets a Navigate to template gutter icon. When several cartridges have it, the icon reads Navigate to template (N cartridges) and opens Choose Template, winning copy first. Cmd+Click on the path opens the winning copy

Find Usages on a template lists the calls that render it, and renaming or moving it rewrites their paths, see ISML Navigation. A pipeline node's <template name="..."> counts too, unless marked dynamic="true"

Resource bundles

Resource.msg and Resource.msgf complete keys from every .properties bundle of your linked cartridges. Each item lists its locales, default first, with the cartridge and bundle on the right, for example app_storefront_base:cart

  • In an empty Resource.msg(''), accepting a key fills the whole call: key, bundle and null. In Resource.msgf the cursor lands where the format arguments go
  • When the call names a bundle, as in Resource.msg('', 'cart'), its keys come first and only the key is inserted
  • The second argument completes bundle names
  • Cmd+Click on a key opens its entries in every locale file

Messages as text

A call with a literal key and bundle folds to the message it returns, so Resource.msg('title', 'loyalty', null) reads "Loyalty rewards". Calls fold when the file opens, in scripts, .ds and .ts files, ${...} and <isscript>

Resource.msg and Resource.msgf calls read as the text of the bundle, with the arguments of msgf in place. Rest the pointer on a message to see the call, click it to open the call, and fold it back from the gutter
  • The default locale's file wins, then the first cartridge on the cartridge path. A key no bundle has doesn't fold, except a require key that falls back to a script path
  • Resource.msgf shows literal arguments in place of {0}, {1} and the others as the code, such as {pdict.points}
  • Rest the pointer on the text to see the call with its parameter hints. Click the text to open the call, and click the marker in the gutter to fold it back
  • Turn it off with Resource.msg() messages in Settings › Editor › General › Code Folding, under B2C Commerce Scripts

A call to the require bundle inside require(...) also resolves the module, see Paths from a resource bundle. Folding needs a license or trial and waits for indexing to finish

Content assets and static files

CallCompletesCmd+Click opens
ContentMgr.getContent('...')Content asset IDs (the content-id of each <content> in your library XML), with the file each comes fromThe asset in the library XML
URLUtils.staticURL, URLUtils.absStatic, URLUtils.httpStatic, URLUtils.httpsStatic, assets.addJs, assets.addCssFiles and folders in cartridge/static/<locale> of linked cartridges, one segment at a timeThe file the server serves, in cartridge path order, default locale first

Full URLs such as https://... or //cdn... are left alone. Renaming a static file updates the paths that point to it

Hooks

HookMgr.callHook and HookMgr.hasHook complete hook names from your cartridges' hooks.json files, with the script and cartridge on each item. The second argument of callHook completes the functions the hook's scripts export

if (HookMgr.hasHook('app.payment.processor.basic_credit')) {
    HookMgr.callHook('app.payment.processor.basic_credit', 'Authorize', order.orderNo, paymentInstrument, paymentProcessor);
}

SFRA's hooksHelper('app.customer.subscription', 'subscribeTo', ...) works the same way. Cmd+Click on the hook name opens its hooks.json entry, on the function name the exported function. For hooks.json itself, see XML & JSON Validation

Hook function parameters

In a script that hooks.json registers for a platform hook point, the function named after the hook's last segment gets typed parameters, such as beforePOST for dw.ocapi.shop.basket.items.beforePOST:

app_custom/cartridge/scripts/hooks/itemsHooks.js
exports.beforePOST = function (basket, items) {
    // basket is dw.order.Basket, items is ProductItemDocument[]
    basket.getAllProductLineItems();
};

This covers the calculate, payment, shipping order, return and Apple Pay hooks, and the dw.ocapi.shop.* hooks that OCAPI and SCAPI call for baskets, customers, auth, orders, products and categories. A function that several hooks share, such as one beforePATCH for baskets and orders, takes the types of all of them, like Basket | Order. These platform types win over a JSDoc @param that says Object or another class. Custom hooks such as app.payment.processor.* need JSDoc, see API & Types

After exports. or module.exports., the functions of the script's platform hooks complete, each with the hooks it serves. Functions the script already exports aren't offered

The Hook function returns a value its hook does not expect inspection checks what the function returns. Most hooks expect a dw.system.Status, so return false in calculate is reported. It reads what the code really returns, not JSDoc: a @returns on the hook function doesn't change what the hook expects, and return validate(basket) is checked against the return statements of validate, whatever its @returns says. A bare return and null pass

Step types

Cmd+Click on a step's function opens it in the module. Show Usages on the export lists the step in steptypes.json, and renaming the exported name rewrites the step, so the job still finds its function

A job step in steptypes.json names its script with module and its function with function. Cmd+Click on the function name opens it in the script, and Find Usages, the usage count and Rename of that function reach steptypes.json:

The step names the function withExample
function of a script step"function": "purgeStaleBaskets"
A chunk keyread-function, process-function, write-function
The @type-id of a script step without function, which runs execute"@type-id": "custom.PurgeBaskets"

Each step is listed once, and a step typed into an open steptypes.json counts at once, saved or not

You renameThe step
The exported name, exports.run or run: in module.exports = { run: run }Follows the new name
The function behind the exportKeeps the export's name
execute of a step without functionKeeps its @type-id

These need a license or trial. For the lens above each step function, see Step types

Forms

server.forms.getForm('profile'), session.forms.profile and SiteGenesis app.getForm('profile') are typed from the form XML, so fields, groups and actions complete and Cmd+Click opens them

var profileForm = server.forms.getForm('profile');
var email = profileForm.customer.email.value;

dwfrm_ names, copies and locales, Find Usages, rename and the form checks are on Forms

Custom attributes and preferences

product.custom., Site.current.preferences.custom. and getCustomPreferenceValue('...') complete the attributes of your metadata XML, each with the type B2C Commerce returns, and Cmd+Click opens the definition. See Custom Attributes

What isn't checked

Most unknown strings aren't marked as errors. A misspelled route, template, key or hook fails only at runtime. To check one, Cmd+Click it: a string that resolves opens its target. Form names and elements are the exception, see Forms

Troubleshooting

SymptomWhat to do
A route, resource key or hook name is missingIts controller, bundle or hooks.json is in a cartridge that isn't linked, or indexing is still running. Bundles must be under templates/resources
A hook function's parameters aren't typedRegister the script in the hooks.json that the cartridge's package.json points to, and export the function under the hook's last segment, for example exports.calculate for dw.order.calculate
server.append('') lists nothingAdd server.extend(module.superModule) and check that another linked cartridge has a controller with the same name
No Navigate to template iconThe path doesn't match a file in templates/<locale> of a linked cartridge
A content asset ID doesn't completeKeep the library XML in the project. Its root element must declare the library namespace
No custom attributes after .custom.Add the object's dw. type with JSDoc, and check that the metadata XML is in the project, see Custom Attributes

On this page