SFRA Hooks

Use hooks to configure a piece of functionality to be called at a specific point in your application flow or at a specific event.

You can use these hooks with a Salesforce B2C Commerce storefront application:

Hook Definition

The package.json file points to the hook file for a cartridge, using the hooks keyword.

{
   "hooks": "./cartridge/scripts/hooks.json"
}

The hook file defines a uniquely named extension point and a script to run. You can implement hook scripts as a CommonJS module. This approach ensures that the script identifier is a module identifier. The value of this identifier can be a relative path or any other valid module identifier.

OCAPI Hook Example

hook.json file defines a dw.ocapi.shop.basket.calculate hook that calls the calculate.js script.

{
    "hooks": [
        {
            "name": "dw.ocapi.shop.basket.calculate",
            "script": "./hooks/cart/calculate.js"
        },
        {
            "name": "app.payment.processor.default",
            "script": "./hooks/payment/processor/default"
        },
        {
            "name": "app.payment.processor.basic_credit",
            "script": "./hooks/payment/processor/basic_credit"
        },
        {
            "name": "app.validate.basket",
            "script": "./hooks/validateBasket"
        }
    ]
}

This example shows an OCAPI hook and several custom hooks. The OCAPI hook runs a script to calculate the cart in the scripts/hooks/cart directory. If you use the System package HookMgr class callHook method, you can call the custom hooks. These hooks are located subdirectories of the scripts/hooks directory.

Custom Hook Example

This example calls the hook from calculate.js.

return dw.system.HookMgr.callHook('app.payment.processor.default', 'Handle', {
            Basket : cart
        });

Running Multiple Hooks for an Extension Point

In a single hooks.json file, you can register multiple modules to call for an extension point. However, you can't control the order in which the modules are called. If you call multiple modules, only the last hook returns a value. All modules are called, regardless of whether any of them return a value.

At run time, B2C Commerce runs all hooks registered for an extension point in all cartridges in your cartridge path. Hooks are executed in the order their cartridges appear on the path. Each cartridge can register a module for the same hook. Modules are called in cartridge-path order for all cartridges in which they are registered.

Note: Hooks are executed in the order of the cartridges on the path. Therefore, when you change the order of the cartridges, you also change the order of hook execution.

Error Logging

Controller and script logging is available.

Example: Custom error log

Error while executing script 'test_cartridge_treatascustom/cartridge/controllers/TestController.js': Wrapped com.demandware.beehive.core.internal.template.ServletAbortException: Requested template 'controller/testController' not found! (test_cartridge_treatascustom/cartridge/controllers/TestController.js#21)
    at test_cartridge_treatascustom/cartridge/controllers/TestController.js:21 (isml)
    at test_cartridge_treatascustom/cartridge/controllers/TestController.js:52 (anonymous)

See also: SFRA Modules