Working with SGJC Controllers

What are controllers?

Controllers are server-side scripts that handle storefront requests. Controllers manage the flow of control in your application, and create instances of models and views to process each storefront request and generate an appropriate response. For example, clicking a category menu item or entering a search term triggers a controller that renders a page.

Controllers are written in JavaScript and Salesforce B2C Commerce script. They must conform to the CommonJS module standard.

The file extension of a controller 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: SGJC Controller Hello.Js

/**
 * A hello world controller.
 *
 * @module controllers/Hello
 */
exports.World = function(){
    response.getWriter().println('Hello World!');
};
exports.World.public = true; 

While it isn't best practice, controllers can also:

Tools

You can use any IDE with a JavaScript editor to develop controllers. However, to upload code, you must either use UX Studio or an upload utility. Upload utilities are available from the Salesforce Commerce Cloud community repositories in GitHUb.

You can also use any standard JavaScript tools, including linters, static code analysis tools.

Request URLs

https://localhost/on/demandware.store/Sites-SiteGenesis-Site/default/Hello-World

See also: B2C Commerce URL Syntax Without SEO.

Reserved Names for Controllers

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.

Secure Requests

You might need to secure access to the exported functions of the controller. A controller function is only called if it has a public property that is set to true. All other functions that do not have this property are ignored by B2C Commerce and lead to a security exception if an attempt is made to call them using HTTP or any other external protocol.

Example: accessible controller

exports.World = function() {};
exports.World.public = true;

Guards

For controllers, SiteGenesis uses the concept of guards to wrap controller functions when they are exported. The functions in the guard module act as a request filter and let you specify multiple levels of access to controller functionality, such as:

• require HTTPS
• require or forbid a certain HTTP method, like GET, POST,...
• require that the current customer is logged in
• require that the function might only be executed as remote include, but not as top-level request

A guard is a wrapper function that encapsulates a delegate function and only invokes it if its guard condition is satisfied. The guard conditions represent single preconditions that can also be combined with each other. The conditions use the B2C Commerce API to determine the properties of the current request and logic to determine whether to continue request processing or throw an error.

Example: require GET

exports.StartCheckout = guard.ensure(['get'], startCheckout);

Example: require HTTPS and that the customer is logged in.

exports.EditProfile = guard.ensure(['get', 'https', 'loggedIn'], editProfile);

Global Variables

var httpUserAgent = request.httpUserAgent;

response.redirect(dw.web.URLUtils.https('Account-Show'));

exports.onSession = function() {
    session.custom.device = getDeviceType();
    return new Status(Status.OK);
};

Request Parameters and Page Meta Data

 render: function (templateName) {
...
        this.CurrentForms = session.forms;
        this.CurrentHttpParameterMap = request.httpParameterMap;
        this.CurrentCustomer = customer;
        this.CurrentSession = session;
        this.CurrentPageMetaData = request.pageMetaData;
        this.CurrentRequest = request;
        try {
            ISML.renderTemplate(templateName, this);
        } catch (e) {
            dw.system.Logger.error('Error while rendering template ' + templateName);
            throw e;
        }
        return this;

}});

Back to top.

Debugging

Almost any JavaScript-related error gets logged in the customerror_* log files, including errors from B2C Commerce scripts and controllers. The error_* log files contain Java-related errors on B2C Commerce, which are probably only useful for B2C Commerce users.

Best Practices

Performance

Only import modules when you need them, not at the top of a module.

Using Controllers with OCAPI

If you intend to build a mobile or native app in addition to your storefront, you can use hooks to create modules that can be used by both your desktop storefront and mobile app.

Jobs

You cannot create jobs with controllers.