Customize Cartridges

Learning Objectives

After completing this unit, you’ll be able to:

List three things you can do with sgmf-scripts.
Describe how to override the app_storefront_base cartridge.
Explain how the global .scss file inherits styles.
Describe how to include JavaScript modules from other cartridges.

You uploaded the SFRA cartridges to your sandbox and registered them in Business Manager. You configured page caching and site URLs to speed up development. Now, it’s time to build a custom cartridge—for example, a faster checkout flow and brand-specific styles for your storefront.

The plan: create an overlay cartridge and put every customization in there. That way, when Salesforce releases a new version of app_storefront_base, you grab the update without tracking down your changes in the base code. You leave app_storefront_base and all plug-in cartridges exactly as Salesforce delivers them, which keeps the backward compatibility guarantee intact and makes future upgrades straightforward.

Override app_storefront_base

Salesforce SFRA so you never edit app_storefront_base directly. All customizations go in an overlay cartridge—one with an app_custom_ prefix—which sits to the left of app_storefront_base on the cartridge path. B2C Commerce searches the path from left to right and picks the first matching file it finds. That file is yours.

Three rules apply to every file type.

Same name: Your file shares a name with the file it overrides.
Same location: Your file sits at the same relative folder path inside your cartridge as the original sits inside app_storefront_base.
Your cartridge goes left: In Business Manager, your custom cartridge sits to the left of app_storefront_base on the cartridge path.

Override a Template

To override app_storefront_base/cartridge/templates/default/product/productDetails.isml, create this file in your custom cartridge.

app_custom_mybrand/cartridge/templates/default/product/productDetails.isml

B2C Commerce finds your template first and stops searching.

Override a Controller

For controllers, use module.superModule to load the base controller’s routes, and then add or replace them in your custom file.

'use strict';
var server = require('server');
var page = module.superModule; // loads next matching controller to the right on the path
server.extend(page);           // inherits all existing routes
server.append('Show', function (req, res, next) {
    var viewData = res.getViewData();
    viewData.product.promoLabel = 'Limited Edition';
    res.setViewData(viewData);
    next();
});
module.exports = server.exports();

server.append adds your step after the original middleware chain runs. If the original route calls an external system—a web service or a payment provider—that call runs twice when you append. In that case, use server.replace to take over the route entirely.

Here’s what you can customize via overlay cartridges.

Element	Description
Hooks	Configure functionality called at a specific point in the app flow or at a specific event.
Modules	Access JavaScript/B2C Commerce script modules that conform to the Modules 1.1.1 CommonJS specification within your storefront script code.
Templates	Override a template by creating one with the same name and relative path as the original.
Models	A JSON object layer that converts proprietary B2C Commerce script API objects into pure JSON objects designed for the storefront. Models also apply business logic.
Controllers and routes	Inherit functionality from another controller and extend it. Replace or add a route. Override a step in the middleware chain. Change access to a route. Add a web service or third-party call.
Forms	Persist form data during a session and store it in system objects or custom objects.
Plug-in cartridges	Include plug-in cartridges on the cartridge path and base path.

Inherit Styles in the Global .scss File

SCSS compilation across cartridges works through aliases that you define in package.json. Open the package.json in your custom cartridge and add a paths object.

"paths": {
  "base": "../storefront-reference-architecture/cartridges/app_storefront_base/",
  "ratings": "../plugin_ratings/cartridges/plugin_ratings/",
  "applepay": "../plugin-applepay/cartridges/plugin_applepay/"
}

In your global .scss file—at cartridges/app_custom_mybrand/cartridge/client/default/scss/global.scss—use the ~base prefix to import style sheets from the base cartridge.

@charset "UTF-8";
@import "~base/variables";
@import "bootstrap/scss/bootstrap";
@import "~base/bootstrap_overrides";
@import "~base/utilities/responsiveUtils";
@import "font-awesome/scss/font-awesome";
@import "components/menu";
@import "~base/components/common";
@import "~base/components/footer";
@import "components/footer";
@import "~base/components/hero";
@import "~base/components/notification";
body {
    font-family: 'Source Sans Pro', sans-serif;
}

The ~base prefix resolves to the directory set by the base property in package.json. Imports without a prefix—like components/menu and components/footer—load files from your custom cartridge. When a ~base import and a local import sit back-to-back, the CSS cascade applies your local rules on top of the base styles.

Run npm run compile:scss and the build tool resolves every alias through package.json, stitching the full style sheet together across cartridges.

Include JavaScript Modules from Other Cartridges

The same paths object in package.json drives client-side JavaScript file includes. Use the alias as a path prefix in a require() call.

'use strict';
var base = require('../base/product/base');

The ../base/ prefix resolves to the directory defined under base in package.json. The rest of the path mirrors the folder structure inside app_storefront_base. Use this pattern to pull in client-side JavaScript from another cartridge and build on it in your custom file. Run npm run compile:js and the build tool compiles across every cartridge in the paths map.

Cartridge Path Substitution

The require() function gives you precise control over where B2C Commerce looks for a file, independent of the cartridge path. Use the prefix that matches your intent.

Prefix	Resolves To
`'./shipping'` or `'../../util'`	Relative to the current file
`'~/cartridge/scripts/cart'`	The root of the current cartridge
`'*/cartridge/scripts/util/array'`	The beginning of the cartridge path
`'dw/catalog/CatalogMgr'`	A B2C Commerce platform API
`'server'`	A named module in the `modules` folder

Troubleshoot

When your changes don’t appear on the server, add an empty code version and reactivate the original.

In Business Manager, select App Launcher.
Select Administration Site Development Code Deployment.
Select Add and enter a name for the new code version.
Select the original code version to reactivate it.

Wrap It Up

In this unit, you used sgmf-scripts to scaffold a cartridge, compile assets, and upload code. You set up the paths object in package.json, which drives both Sass and JavaScript imports across cartridges. You used the same-name, same-location pattern to override templates and controllers without touching app_storefront_base. Now, take the final quiz and earn your badge.

时间估计

主题

需要帮助？