Controllers are server-side scripts that handle storefront requests. Controllers manage the flow of data in your application, and create
ViewModels to process each storefront request as a
route and generate an appropriate response. For example, in a storefront application, clicking a category menu item or entering a search term triggers a controller that renders a page.
A controller's file extension can be either .ds or .js. Controllers must be located in the
controllers folder at the top level of the cartridge. Exported methods for controllers must be explicitly made public to be available to handle storefront requests.
Example: SFRA Base Cartridge Controller Hello.Js
Controllers can use
Import script modules. Any B2C Commerce script can be made into a CommonJS module and required by a controller.
Import B2C Commerce packages, instead of using the
importPackagesmethod. This approach is the recommended way to reference functionality from a controller. You can also use the require method to import a single B2C Commerce class. For example:
While it isn't best practice, controllers can also:
Call other controllers. We don't recommend that controllers call each other, because controller functionality is self-contained to avoid circular dependencies. Sometimes, however, such as calling non-public controllers during the checkout process, it's unavoidable.
Call pipelets. We strongly discourage calling pipelets from within a controller. However, it's allowed while there are still pipelets that don't have equivalent B2C Commerce script methods.
Call pipelines that don't end in interaction continue nodes. This technique is only intended for use with existing link cartridges and is highly discouraged for general development.
It isn't currently possible to call pipelines that end in interaction continue nodes.
A request URL for a controller has the format
controller-function. For example, the request URL for the Hello.js controller World function looks like:
For more information, see B2C Commerce URL Syntax Without SEO.
B2C Commerce has several system names that are reserved and can't be used for custom controllers and their functions. For a full list, see System Pipelines and Controllers in our Legacy Developer Documentation.
SFRA uses the
server.res objects for request and response data. While global variables are still available, we don't recommend that you use them.
customerror_* log files, including errors from B2C Commerce scripts and controllers. The
error_* log files contain Java-related errors on B2C Commerce, and are probably less useful to non-B2C Commerce employees
Error.js controller services uncaught errors. By default, B2C Commerce returns a 410 error, which indicates that the resource is no longer available. If you prefer 404, it's fine to use as long as the related ISML template doesn't include
<isinclude> tags. When you want to handle these errors explicitly, you can use
Only require modules when you need them, not at the top of a module.
You can build a mobile or native app in addition to your storefront. If you want to create modules that work both for a desktop storefront and a mobile app, use hooks.