sfcc-cartridge-development（sfcc 墨盒开发）

SFCC Cartridge Development

Overview

Build custom cartridges for Salesforce Commerce Cloud (SFCC) using the Storefront Reference Architecture (SFRA), server-side JavaScript controllers, ISML templates, models, and the B2C Commerce Script API. This skill covers cartridge layering and the override mechanism, route handling with server.js, form handling, OCAPI/SCAPI integration, and Job Framework usage for scheduled data processing.

When to Use This Skill

• When building a custom feature cartridge that extends SFRA functionality
• When overriding or extending existing SFRA controllers, templates, or models
• When implementing custom checkout steps or payment integrations on SFCC
• When creating scheduled jobs for data import/export (product feeds, order sync)
• When building OCAPI hooks or SCAPI integrations for headless storefronts

Core Instructions

1. Set up the cartridge structure and layering SFCC uses a cartridge path for layering. Cartridges higher in the path override those lower. A custom cartridge extends app_storefront_base: int_acme_custom/ ├── cartridge/ │ ├── controllers/ # Server-side JS controllers │ ├── models/ # Data model wrappers │ ├── scripts/ # Business logic helpers │ ├── templates/ │ │ └── default/ # ISML templates │ ├── forms/ │ │ └── default/ # Form definitions (XML) │ ├── static/ │ │ └── default/ │ │ ├── css/ │ │ └── js/ │ └── int_acme_custom.properties # Cartridge metadata └── package.json Set the cartridge path in Business Manager: int_acme_custom:app_storefront_base int_acme_custom.properties: ## cartridge.properties demandware.cartridges.int_acme_custom.multipleLanguageStorefront=true
2. Create a server-side controller Controllers in SFRA use server.js for route registration: // controllers/CustomPage.js 'use strict'; var server = require('server'); var cache = require('*/cartridge/scripts/middleware/cache'); var consentTracking = require('*/cartridge/scripts/middleware/consentTracking'); /** * CustomPage-Show: Renders a custom content page * @name CustomPage-Show * @function * @memberof CustomPage * @param {middleware} - server.middleware.https * @param {middleware} - consentTracking.consent * @param {middleware} - cache.applyDefaultCache * @param {querystringparameter} - cid: content asset ID * @param {renders} - isml * @param {serverfunction} - get */ server.get('Show', server.middleware.https, consentTracking.consent, cache.applyDefaultCache, function (req, res, next) {var ContentMgr = require('dw/content/ContentMgr'); var ContentModel = require('*/cartridge/models/content'); var contentId = req.querystring.cid; var apiContent = ContentMgr.getContent(contentId); if (!apiContent) {res.setStatusCode(404); res.render('error/notFound'); return next();} var contentModel = new ContentModel(apiContent); res.render('custom/contentPage', {content: contentModel, breadcrumbs: [{htmlValue: 'Home', url: '/'}, {htmlValue: contentModel.name, url: ''}]}); next();}); /** * CustomPage-Submit: Handles form POST submissions */ server.post('Submit', server.middleware.https, function (req, res, next) {var Transaction = require('dw/system/Transaction'); var CustomObjectMgr = require('dw/object/CustomObjectMgr'); var form = req.form; var name = form.name; var email = form.email; // Validate input if (!name ||!email) {res.json({success: false, error: 'Name and email are required.'}); return next();} try {Transaction.wrap(function () {var co = CustomObjectMgr.createCustomObject('AcmeSubmissions', email); co.custom.name = name; co.custom.submittedAt = new Date();}); res.json({success: true, message: 'Submission received.'});} catch (e) {var Logger = require('dw/system/Logger'); Logger.error('Submission failed: {0}', e.message); res.json({success: false, error: 'An error occurred. Please try again.'});} next();}); module.exports = server.exports();
3. Extend an existing SFRA controller Use server.extend to add or modify routes on an existing controller: // controllers/Cart.js — extending app_storefront_base Cart 'use strict'; var server = require('server'); var page = module.superModule; // Reference to the base Cart controller server.extend(page); /** * Cart-Show: Append custom data to the Cart page */ server.append('Show', function (req, res, next) {var viewData = res.getViewData(); // Add custom upsell products to the cart page var ProductMgr = require('dw/catalog/ProductMgr'); var ArrayList = require('dw/util/ArrayList'); var upsells = new ArrayList(); var basket = require('dw/order/BasketMgr').getCurrentBasket(); if (basket) {var items = basket.getAllProductLineItems(); for (var i = 0; i < items.length; i++) {var recommendations = items[i].product.getRecommendations(); for (var j = 0; j < Math.min(recommendations.length, 2); j++) {upsells.push(recommendations[j].getRecommendedItem());}}} viewData.upsellProducts = upsells.toArray().slice(0, 4); res.setViewData(viewData); next();}); /** * Cart-AddCustomItem: New route added to the Cart controller */ server.post('AddCustomItem', function (req, res, next) {var BasketMgr = require('dw/order/BasketMgr'); var Transaction = require('dw/system/Transaction'); var ProductMgr = require('dw/catalog/ProductMgr'); var productId = req.form.pid; var quantity = parseInt(req.form.quantity, 10) || 1; var product = ProductMgr.getProduct(productId); if (!product ||!product.isOnline()) {res.json({error: true, message: 'Product not available.'}); return next();} var basket = BasketMgr.getCurrentOrNewBasket(); Transaction.wrap(function () {var pli = basket.createProductLineItem(productId, basket.getDefaultShipment()); pli.setQuantityValue(quantity);}); res.json({success: true, itemCount: basket.productQuantityTotal}); next();}); module.exports = server.exports();
4. Write ISML templates <--- templates/default/custom/contentPage.isml ---> <isdecorate template="common/layout/page"> <isscript> var assets = require('*/cartridge/scripts/assets'); assets.addCss('/css/custom/content.css'); assets.addJs('/js/custom/content.js'); </isscript> <div class="container custom-content-page"> <div class="row"> <div class="col-12"> <nav aria-label="Breadcrumb"> <ol class="breadcrumb"> <isloop items="${pdict.breadcrumbs}" var="crumb" status="loopstatus"> <isif condition="${loopstatus.last}"> <li class="breadcrumb-item active">${crumb.htmlValue}</li> <iselse/> <li class="breadcrumb-item"> <a href="${crumb.url}">${crumb.htmlValue}</a> </li> </isif> </isloop> </ol> </nav> <h1>${pdict.content.name}</h1> <div class="content-body"> <isprint value="${pdict.content.body}" encoding="off"/> </div> </div> </div> </div> </isdecorate>
5. Create a data model wrapper // models/content.js 'use strict'; var URLUtils = require('dw/web/URLUtils'); /** * Content model wrapping a dw.content.Content API object * @param {dw.content.Content} contentObj - Content API object * @constructor */ function ContentModel(contentObj) {this.id = contentObj.ID; this.name = contentObj.name || contentObj.ID; this.body = contentObj.custom.body? contentObj.custom.body.markup: ''; this.online = contentObj.online; this.url = URLUtils.url('CustomPage-Show', 'cid', contentObj.ID).toString(); this.pageTitle = contentObj.pageTitle || this.name; this.pageDescription = contentObj.pageDescription || ''; this.pageKeywords = contentObj.pageKeywords || '';} module.exports = ContentModel;
6. Build a scheduled job for data processing // scripts/jobs/syncInventory.js 'use strict'; var Status = require('dw/system/Status'); var Logger = require('dw/system/Logger').getLogger('inventory-sync', 'acme'); var HTTPClient = require('dw/net/HTTPClient'); var Transaction = require('dw/system/Transaction'); var ProductInventoryMgr = require('dw/catalog/ProductInventoryMgr'); /** * Job step: Fetch inventory from external ERP and update SFCC * @param {dw.util.HashMap} params - Job step parameters * @returns {dw.system.Status} - Job status */ function execute(params) {var apiUrl = params.get('apiUrl'); var apiKey = params.get('apiKey'); var inventoryListId = params.get('inventoryListId') || 'default'; var httpClient = new HTTPClient(); httpClient.open('GET', apiUrl); httpClient.setRequestHeader('Authorization', 'Bearer ' + apiKey); httpClient.setRequestHeader('Accept', 'application/json'); httpClient.setTimeout(30000); httpClient.send(); if (httpClient.statusCode!== 200) {Logger.error('ERP API returned status {0}', httpClient.statusCode); return new Status(Status.ERROR, 'API_ERROR', 'ERP API returned ' + httpClient.statusCode);} var inventory = JSON.parse(httpClient.text); var inventoryList = ProductInventoryMgr.getInventoryList(inventoryListId); if (!inventoryList) {return new Status(Status.ERROR, 'LIST_NOT_FOUND', 'Inventory list not found');} var updated = 0; var errors = 0; inventory.items.forEach(function (item) {try {Transaction.wrap(function () {var record = inventoryList.getRecord(item.sku); if (!record) {record = inventoryList.createRecord(item.sku);} record.setAllocation(item.quantity); if (item.inStockDate) {record.setInStockDate(new Date(item.inStockDate));}}); updated++;} catch (e) {Logger.error('Failed to update SKU {0}: {1}', item.sku, e.message); errors++;}}); Logger.info('Inventory sync complete: {0} updated, {1} errors', updated, errors); return new Status(Status.OK, 'SYNC_COMPLETE', updated + ' records updated');} module.exports.execute = execute;

Examples

OCAPI hook for order creation

// hooks/order/ocapiHooks.js
'use strict';

var Status = require('dw/system/Status');
var Logger = require('dw/system/Logger').getLogger('ocapi-hooks', 'acme');

/**
 * OCAPI after-POST hook for order creation
 * Called after a new order is placed via OCAPI
 */
exports.afterPOST = function (order) {
    try {
        // Send order data to external analytics
        var HTTPClient = require('dw/net/HTTPClient');
        var httpClient = new HTTPClient();
        httpClient.open('POST', 'https://analytics.acme.com/orders');
        httpClient.setRequestHeader('Content-Type', 'application/json');
        httpClient.send(JSON.stringify({
            orderId: order.orderNo,
            total: order.totalGrossPrice.value,
            currency: order.currencyCode,
            itemCount: order.productLineItems.length,
            customerEmail: order.customerEmail,
        }));

        if (httpClient.statusCode !== 200) {
            Logger.warn('Analytics push failed for order {0}: HTTP {1}',
                order.orderNo, httpClient.statusCode);
        }
    } catch (e) {
        Logger.error('OCAPI hook error: {0}', e.message);
    }

    return new Status(Status.OK);
};

Register in hooks.json:

{
    "hooks": [
        {
            "name": "dw.ocapi.shop.order.afterPOST",
            "script": "./hooks/order/ocapiHooks"
        }
    ]
}

Form definition and server-side validation

<!-- forms/default/contactus.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
    <field formid="name" label="form.contactus.name"
           type="string" mandatory="true" max-length="100"/>
    <field formid="email" label="form.contactus.email"
           type="string" mandatory="true" max-length="254"
           regexp="^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"/>
    <field formid="message" label="form.contactus.message"
           type="string" mandatory="true" max-length="2000"/>
    <action formid="submit" label="form.contactus.submit" valid-form="true"/>
</form>

// controllers/ContactUs.js
'use strict';
var server = require('server');

server.get('Show', function (req, res, next) {
    var contactForm = server.forms.getForm('contactus');
    contactForm.clear();
    res.render('contactus/form', { contactForm: contactForm });
    next();
});

server.post('Submit', function (req, res, next) {
    var contactForm = server.forms.getForm('contactus');

    if (contactForm.valid) {
        var Transaction = require('dw/system/Transaction');
        var CustomObjectMgr = require('dw/object/CustomObjectMgr');

        Transaction.wrap(function () {
            var co = CustomObjectMgr.createCustomObject(
                'ContactSubmission',
                require('dw/util/UUIDUtils').createUUID()
            );
            co.custom.name = contactForm.name.value;
            co.custom.email = contactForm.email.value;
            co.custom.message = contactForm.message.value;
        });

        res.json({ success: true });
    } else {
        res.json({
            success: false,
            fields: {
                name: contactForm.name.error || null,
                email: contactForm.email.error || null,
                message: contactForm.message.error || null,
            }
        });
    }
    next();
});

module.exports = server.exports();

Best Practices

• Follow the cartridge layering convention -- custom cartridges override base cartridges; use module.superModule to extend rather than replace controllers
• Use server.append over server.replace -- appending preserves the original controller logic and other cartridge extensions; replacing breaks the chain
• Wrap all database writes in Transaction.wrap() -- SFCC requires explicit transactions for all persistent changes; missing transactions cause silent failures
• Use the Script API, not direct database access -- SFCC has no direct SQL access; always use *Mgr classes (ProductMgr, BasketMgr, OrderMgr) for data operations
• Log with categorized loggers -- use Logger.getLogger(category, prefix) so log messages can be filtered in Log Center by category
• Never hardcode site-specific values -- use Site Preferences (custom site preferences in Business Manager) for configurable values like API keys and feature flags
• Test with the SFCC sandbox -- always develop and test on a sandbox instance before deploying to staging or production
• Use the SFCC linting rules -- enforce 'use strict' and check for missing next() calls in controllers, which cause request hanging

Common Pitfalls

Related Skills

• @erp-integration
• @ecommerce-caching
• @ecommerce-seo
• @pci-dss-compliance
• @product-data-modeling